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Preface 


Intended Audience 

This manual is intended primarily for systems and applications pro¬ 
grammers, or any other programmers whose work requires the use of 
operating system features outside of the language (such as system ser¬ 
vices), advanced Ada® features (such as tasking), or more than one VAX^ 
language. The reader should have a working knowledge of Ada and some 
familiarity with the VAX/VMS operating system. 


Structure of This Document 

This manual has eight chapters and one appendix: 

• Chapter 1 introduces VAX Ada. 

• Chapter 2 discusses VAX Ada input-output, giving details about file 
sharing, record locking, and the VAX Ada input-output packages, as 
well as summary information about the VAX/VMS File Definition 
Language and the specification of file names. 

• Chapter 3 explains how VAX Ada objects and types are represented 
and sized, and gives information on sharing object storage among Ada 
and non-Ada routines. 

• Chapter 4 describes the VAX Ada parameter-passing mechanisms and 
import-export pragmas, and discusses how to write mixed-language 
programs that involve VAX Ada. 

• Chapter 5 shows how to call system routines (system services, Run¬ 
Time Library routines, and so on). 

• Chapter 6 describes the implementation of VAX Ada exception han¬ 
dling and discusses the importing and exporting of VAX conditions and 
Ada exceptions. 

• Chapter 7 discusses tasking issues, including issues related to calling 
non-Ada routines (such as system services) from tasks. 


xiii 


VAX is a trademark of Digital Equipment Corporation 

Ada is a registered trademark of the U.S. Government, Ada Joint Program Office 




• Chapter 8 gives information on how to make VAX Ada programs more 
efficient. 

• Appendix A lists all of the VAX Ada packages, and gives the 
specifications for the packages CONDITION-HANDLING, 
TASKING-SERVICES, CONTROL_C_INTERCEPTION, and 
MATH_LIB. 


Associated Documents 

For more information on VAX Ada language details, see the VAX Ada 
Language Reference Manual; for more information on how to develop 
and run VAX Ada programs using the VAX Ada library manager and 
debugger, see Developing Ada Programs on VAX/VMS. You should also 
have all or most all of the VAX/VMS system documentation available for 
reference. 

Some recent Ada textbooks that may be of interest are 

• Barnes, J.G.P. Programming in Ada. Reading, Massachusetts: Addison- 
Wesley, October, 1983. 

• Booch, Grady. Software Engineering with Ada. Menlo Park, California: 
The Benjamin/Cummings Publishing Company, Inc., 1983. 

• Cherry, G.W. Parallel Programming in ANSI Standard Ada. Reston, 
Virginia: Reston Publishing Company, Inc., 1984. 

• Gehani, Narain. Ada, Concurrent Programming. Englewood Cliffs, New 
Jersey: Prentice Hall, Inc., 1984. 

• Habermann, A.N., and D.E. Perry. Ada for the Experienced Programmer. 
Reading, Massachusetts: Addison-Wesley, 1983. 

• Weiner, Richard, and Richard Sincovec. Programming in Ada. New 
York: John Wiley & Sons, 1983. 



Conventions Used in This Document 


Convention 

Meaning 

mu 

A symbol with a one- to six-character abbre¬ 
viation indicates that you press a key on the 
terminal, for example, 1 RET | . 

|CTRL/x| 

The phrase CTRL/x indicates that you must 
press the key labeled CTRL while you si¬ 
multaneously press another key, for example, 
CTRL/C, CTRL/Y, CTRL/O. 

$ SHOW TIME 

Interactive examples show all output lines or 

05-JUN-1985 11:55:22 

prompting characters that the system prints 
or displays in black letters. All user-entered 
commands are shown in red letters. 


A horizontal ellipsis in a figure or example 
indicates that not all of the statements are 
shown. 

task 

Boldface indicates Ada reserved words. 

type—name 

Italicized words in syntax descriptions indicate 
descriptive prefixes that are intended to give 
additional semantic information rather than to 
define a separate syntactic category. 

[expression] 

Square brackets indicate that the enclosed item 
is optional. 

{, mechanism_name } 

Braces indicate that the enclosed item may be 
repeated zero or more times. 

quotation marks 

The term quotation marks is used to refer 

apostrophes 

to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 


xv 








* 


Chapter 1 

Introduction 


The Ada programming language has been designed as a general-purpose 
language, suited in particular for writing large-scale and real-time systems 
programs. For example, Ada is strongly typed, provides for exact or 
approximate numerical calculations, supports concurrency, and allows 
separate compilation of program units. The language is specified in 
ANSI/MIL-STD-1815A-1983, Reference Manual for the Ada Programming 
Language , which has been reproduced, with supplementary DIGITAL 
insertions, as the VAX Ada Language Reference Manual. 

VAX'® Ada c * ; implements the ANSI standard Ada programming language 
on the VAX/VMS operating system. It includes all of the standard lan¬ 
guage features plus packages, attributes, and pragmas designed to allow 
Ada programmers to work efficiently in a VAX/VMS environment and 
make use of the VAX/VMS operating system. Like other languages in the 
VAX Common Language Environment, VAX Ada conforms to the VAX 
Procedure Calling Standard, interacts with the VAX/VMS Common Run¬ 
Time Library, uses VAX/VMS Record Management Services to implement 
input-output, and depends on the VAX Condition Handling Facility to 
implement exception handling. The compiler produces highly optimized 
object code, and makes use of the VAX hardware instruction set. 
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VAX Ada is described in the following chapters, with a focus on those 
VAX Ada features that allow you to interact with the VAX/VMS operating 
system, as well as with other VAX languages. For example, the chapter 
on input-output describes how you can use Ada form strings to control 
the kinds of files used by your program and to make full use of the 
VAX/VMS file handling and file sharing operations (operations that are 
also supported by other VAX languages). The chapter on object and type 
representations describes how Ada types are represented (as other VAX 
language types are represented) on VAX machines. 

Similarly, the chapters on mixed-language programming, calling system 
services, exception-handling, and tasking all point to VAX Ada's inte¬ 
gration into the Common Language Environment. By being able to call 
VAX/VMS system, Run-Time Library, and callable utility routines from 
Ada subprograms or tasks, you can write programs that make efficient 
use of the operating system. By being able to call other languages and 
handle exceptions from both Ada and non-Ada code, you can make use 
of existing non-Ada routines, or take advantage of other-language features 
that may be suitable for your application. 
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Chapter 2 

Input-Output Facilities 


Although VAX Ada allows you to invoke VAX/VMS input-output system 
services and Record Management Services (RMS) directly (see Chapters 4 
and 5), for most applications it is not necessary to do so. The VAX Ada 
predefined input-output packages provide a rich and comprehensive set of 
file operations, and each input-output package is tailored for operations to 
a specific kind of file. 

VAX Ada predefines the packages 

SEQUENTIAL—IO 

DIRECT_IO 

RELATIVE—IO 

INDEXED—IO 

SEQUENTIAL_MIXED_IO 

DIRECT_MIXED_IO 

RELATIVE_MIXED_IO 

INDEXED_MIXED_IO 

TEXT_IO 

Of these, the packages SEQUENTIAL_IO, DIRECT-IO, and TEXT_IO are 
predefined by the Ada language; the rest are predefined by the VAX Ada 
implementation. All of the package specifications, as well as explanations 
of the operations provided by each package, are presented in Chapter 14 
of the VAX Ada Language Reference Manual. 

The VAX Ada predefined packages and their operations are implemented 
using RMS file organizations and facilities. This chapter describes the 
implementation and explores some of its implications: 

• Section 2.1 explains the kinds of VAX Ada files that are available for 
input-output. 

• Sections 2.2 and 2.3 explain how to control the characteristics of 
external files. 

• Sections 2.4 and 2.5 explain how file sharing and locking work in 
VAX Ada. 
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• Section 2.6 gives the default file attributes provided by the input-output 
packages, and includes examples of using each kind of package. 

• Section 2.7 describes the interaction between input-output and tasking. 

• Section 2.8 mentions the VAX Ada input-output error-reporting facili¬ 
ties. 

The information in this chapter is presented with the assumption that 
you are generally familiar with the Ada language and the VAX Ada 
predefined input-output packages, as described in Chapter 14 of the VAX 
Ada Language Reference Manual. You should also have some familiarity 
with RMS file organizations and access methods, know how to work with 
VAX/VMS file specifications and directories, and have some familiarity 
with the VAX/VMS File Definition Language (FDL). If you do not, the 
Guide to VAX/VMS File Applications gives a thorough introduction to 
RMS files and FDL. For more detailed information about RMS and RMS 
services, see the VAX/VMS Record Management Services Reference Manual; 
for more detailed information on FDL, see the VAX/VMS File Definition 
Language Facility Reference Manual. 


2.1 Files and File Access 

To input and output data to and from an Ada program, you must first 
associate the file objects in your program with external files. All of the 
VAX Ada input-output packages supply CREATE and OPEN procedures 
that allow you to make this association: each CREATE procedure creates 
a new external file and then associates a file object with it; each OPEN 
procedure associates a file object with an existing external file. 

When you create or open a VAX Ada file object, the external file with 
which it is associated is a VAX RMS file that has a particular kind of 
organization and that allows a particular kind of access. Each element 
in the file is associated with an RMS record that has a particular kind of 
format. A default organization, access, and record format is determined by 
the input-output package that you use to create the file. Depending on the 
package, you can change these defaults with a CREATE or OPEN FORM 
parameter. Section 2.3.3 discusses default external file attributes in more 
detail. 

The following sections summarize how file objects, called Ada files in this 
chapter, and external files (RMS files) are related. Detailed definitions 
of Ada files are given in Chapter 14 of the VAX Ada Language Reference 
Manual; detailed definitions of RMS file organizations and record formats 
are given in the Guide to VAX/VMS File Applications. 
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2.1.1 Ada Sequential Files 

An Ada sequential file is defined as a set of file elements occupying 
consecutive positions in linear order. Values are transferred in the order 
in which they are read or written to the file, and when the file is opened, 
transfer starts from the beginning of the file. 

An Ada sequential file can be associated with an RMS file of any organi¬ 
zation; the records in the RMS file may have fixed-length, variable-length, 
variable-length with fixed-length control (VFC), or stream format. 

The packages SEQUENTIAL_IO and SEQUENTIAL_MIXED_IO provide 
sequential access to Ada sequential files. 


2.1.2 Ada Direct Files 

An Ada direct file is defined as a set of file elements occupying consecutive 
positions in linear order. Values can be transferred to or from an element 
of the file at any selected position. The position of an element is specified 
by its index, which is an integer in the range from 1 to (2**31)-1 (a value 
of the subtype POSITIVE_COUNT). The first element, if any, has an 
index of one; the index of the last element, if any, is called the current 
size. The current size is zero if there are no elements. 

An open Ada direct file has a current index, which is set to one when the 
file is created or opened. The current index determines which element will 
be involved in the next read or write operation. 

An Ada direct file can be associated only with an RMS file with sequential 
organization; the records in the RMS file must have fixed-length format. 

The packages DIRECT_IO and DIRECT_MIXED_IO provide direct access 
to Ada direct files. 


2.1.3 Ada Relative Files 

An Ada relative file is a set of fixed-length cells occupying consecutive 
positions in linear order. Cells in a relative file are numbered from 1 to 
(2**31)-1 (values of the subtype POSITIVE-COUNT); the number of a 
cell is called its index. The cells in a relative file can either be empty or 
can contain fixed- or variable-length elements. 
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An open Ada relative file has a current index, which is set to one when 
the file is created or opened. The current index determines which element 
will be involved in the next read or write operation. The concept of size 
does not apply to relative files; end of file is true if, starting at the current 
index, all cells are empty. 

An Ada relative file can be associated only with an RMS file with relative 
organization; the records in the RMS file may have fixed-length, variable- 
length, or variable-length with fixed-length control (VFC) format. 

The packages RELATIVE_IO and RELATIVE_MIXED_IO provide relative 
access to Ada relative files. 


2.1.4 Ada Indexed Files 

An Ada indexed file is a set of file elements that are ordered by predefined 
keys. Each element has at least one primary key (numbered 0), and may 
have as many as 254 alternate keys (numbered 1 to 254). You define keys 
in the form string (the FORM parameter) when the file is created. The 
elements of an indexed file can be accessed by any key. 

An open Ada indexed file has a next element, which is the first element 
determined by the primary key when the file is first opened; the next 
element is redefined after each successful read operation, or it may be 
reset to the first sequential element according to the specified key. The 
concept of size does not apply to Ada indexed files: end of file is true if, 
starting at next element in the file, no elements exist. 

An Ada indexed file can be associated only with an RMS file with in¬ 
dexed organization; the records in the RMS file may have fixed-length or 
variable-length (VFC or stream) format. 

The packages INDEXED_IO and INDEXED_MIXED_IO provide indexed 
access to Ada indexed files. 


2.1.5 Ada Text Files 

An Ada text file is defined as a sequence of pages, where a page is a 
sequence of lines, and a line is a sequence of characters. Characters, lines, 
and pages are all numbered starting from 1 and range to (2**31)-1 (the 
numbers are values of the subtype POSITIVE-COUNT). The number of a 
character is called its column number. The line terminator that marks the 
end of a line has a column number that is one more than the number of 
characters in the line. 
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The current column number in a text file is the column number of the 
next character or line terminator to be read or written. Similarly, the 
current line number is the number of the current line, and the current 
page number is the number of the current page. 

An Ada text file may be associated only with an RMS file with sequential 
organization. The records in the RMS file may have fixed-length or 
variable-length format. 

The package TEXT_IO provides sequential access to Ada text files. 


2.2 Naming External Files 

In VAX Ada, external files are identified by VAX/VMS file specifications. 
All of the CREATE and OPEN procedures provided by the VAX Ada 
input-output packages have a NAME parameter that allows you to name 
an external file to be associated with a particular file object. The value of 
the NAME parameter can either be a string that denotes a VAX/VMS file 
specification or a logical name, or it can be a null string (the default). If 
the value of NAME is a file specification, the Ada file object given by the 
FILE parameter in the particular CREATE or OPEN procedure is associated 
with an external file named by that specification. If the value of NAME is 
a null string, then the external file is a temporary file that is deleted when 
the program has finished executing. 

You can also use the FORM parameter (see Section 2.3) to identify an ex¬ 
ternal file. The File Definition Language (FDL) attributes FILE DEFAULT— 
NAME allow you to give file specification information that will be used by 
default if any of that information is omitted from the string given for the 
NAME parameter. Thus, in the following example, the external file will 
have the specification SOME_FILE.DAT. 

CREATE(FILE => F, 

MODE => OUTJFTLE, 

NAME => "SOMEJFILE", 

FORM => "FILE; DEFAULT.NAME '.DAT'"); 

Note, however, that if you specify a default file name in the FORM 
parameter, but omit a value for the NAME parameter, the external file is 
still a temporary file that is deleted when the file is closed, and the default 
name is ignored. 

The following sections summarize briefly how to write file specifications 
and how to write and use logical names in place of file specifications. For 
a full description of file specifications and logical names, see the Guide to 
VAX/VMS File Applications and the VAX/VMS DCL Dictionary. 
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2.2.1 File Specification Syntax 


A file specification identifies an external file or a device on the VAX/VMS 
operating system. The syntax is as follows: 

node::device:[directory]filename.type;version 

node 

The name of a network node. This element is applicable only to systems 
that are part of a network. 

device 

The name of the device on which the file is stored or is to be written. 

directory 

The name of the directory (and any subdirectories) under which the file 
is cataloged on the specified device. You can delimit the directory name 
with square brackets, as shown, or with angle brackets (< > ). Directory 
names apply only to files stored on disk devices. 

filename 

The name of the file; the maximum length is 39 characters (upper- or 
lowercase letters, digits, underscore (_), or dollar sign ($)). A file name 
specification is appropriate only for files stored on mass storage devices. 

type 

The type of the file; the maximum length is 39 characters (upper- or low¬ 
ercase letters, digits, underscore (_), or dollar sign ($)). By convention, 
the type is an abbreviation that describes the kind of data in the file. You 
must use a period to separate filename and type. A type specification is 
appropriate only for files stored on mass storage devices. 

version 

A decimal number that specifies which version of the file is desired. The 
version number is incremented by one each time a new version of a file 
is created. The maximum version number is 32767. You can use either a 
semicolon, as shown, or a period to separate type and version. A version 
number is appropriate only for files stored on mass storage devices. 

You need not explicitly state all the elements of a file specification. If you 
omit an element, a default value is assumed. For more information, see 
the VAX/VMS DCL Dictionary . 

You can use VAX Ada form strings (that is, the value of the FORM 
parameter in an input-output package CREATE or OPEN procedure) to 
further define or change default file specifications. See Section 2.3.3. 
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2.2.2 Logical Names 


Logical names are names that represent files, directories, or physical 
devices. Every logical name is paired with an equivalence string (or list of 
equivalence strings). An equivalence string is a character string denoting, 
for example, a full file specification, a device name, or another logical 
name. Thus, logical names are a convenient shorthand for file names to 
which you refer frequently. See the VAX/VMS DCL Dictionary and Guide 
to VAX/VMS File Applications for complete explanations of logical names 
and examples of their use. In particular, see the descriptions of the DCL 
ASSIGN and DEFINE commands. 

Logical names are maintained by the system in four logical name tables: 
your process table, the job table for your process, your group table, 
and the system table. These tables are described in the VAX/VMS DCL 
Dictionary. 

By default, VAX/VMS creates a set of logical names for you when you log 
in. The predefined names of interest when doing VAX Ada input-output 
are listed in Table 2-1. 

Table 2-1: Predefined (Default) Logical Names 


Logical Name 

Table in Which 
Name is Stored 

What the Name Represents 

SYS$COMMAND 

Process 

Initial device or file from which 
DCL reads input (the original 
SYSSINPUT stream). 

SYS$DISK 

Process 

Default device established at 
login or changed by the SET 
DEFAULT command. 

SYS$ERROR 

Process 

Default device or file to which 
the system writes error mes¬ 
sages generated by warnings, 
errors, and severe errors. 

SYSSINPUT 

Process 

Default file or device (input 
stream) from which DCL reads 
input for the process. 

SYS$LOGIN 

Job 

Device and directory estab¬ 
lished at login as the home 
directory for the process. 
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Table 2-1: (Cont.) Predefined (Default) Logical Names 


Logical Name 

Table in Which 

Name is Stored 

What the Name Represents 

SYS$NET 

Process 

The source process that in¬ 
vokes a target process in 
DECnet-VAX task-to-task com- 



munication. When opened by 
the target process, SYS$NET 
represents the logical link 
over which that process can 
exchange data with its partner. 
SYS$NET is defined only dur¬ 
ing task-to-task communication. 
(Note that task-to-task com¬ 
munication refers to tasks that 



are VAX/VMS images running 
in the context of a process, not 
Ada tasks). 

SYS$OUTPUT 

Process 

Default file or device (output 
stream) to which DCL writes 
output for the process. 

SYS$SCRATCH 

Job 

Default device and directory 
to which temporary files are 
written. 

TT 

Process 

Default device name for termi¬ 
nals. 

ADA$INPUT 

Determined by user 

Default device or file from 
which Ada TEXT_IO input 
is read; SYS$INPUT if not 
defined by the user. 

ADA$OUTPUT 

Determined by user 

Default device or file to which 
Ada TEXT—IO output is writ¬ 
ten; SYS$OUTPUT if not 
defined by the user. 


The names SYSSCOMMAND, SYS$ERROR, SYS$INPUT, and 
SYS$OUTPUT represent process permanent files (files that are open 
for the life of your process). They have different equivalence strings as¬ 
sociated with them depending on whether they are used interactively, 
in a batch job, or in a command procedure. They can also be redefined. 
The VAX/VMS DCL Dictionary explains and demonstrates the use of these 
names; Table 2-2 gives the source of the equivalence strings associated 
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with them. Note in Table 2-2 that the following definition of terms is 
used: terminal means the device name of your terminal; disk means the 
device name of the initial default device; and log file means the batch job 
log file. 

Table 2-2: Equivalence String Derivations for Process 
Permanent File Logical Names 


Logical 

Name 

Interactive 

Mode 

Batch 

Mode 

Command 

Procedure 

SYS$COMMAND 

Terminal 

Disk 

Terminal 

SYS$INPUT 

Terminal 

Disk 

Disk 

SYS$ERROR 

Terminal 

Log file 

Terminal 

SYS$OUTPUT 

Terminal 

Log file 

Terminal 


2.3 Specifying External File Attributes 

The CREATE and OPEN procedures in the VAX Ada input-output pack¬ 
ages all have a FORM parameter that allows you to specify the system- 
dependent attributes of an external file. Most of the time, you will not 
need to use the FORM parameter when you create or open a file, because 
each input-output package assumes certain attributes for the external file 
by default. In fact, you never need to specify a value for FORM when 
you open an existing file. You do need to specify it under the following 
conditions when you create a file: 

• With a relative or direct file where the item by which the input- 
output package is instantiated is unconstrained, you must specify the 
maximum size of the file elements (records) in bytes. 

• With a relative mixed-type or direct mixed-type file, you must specify the 
maximum size of the file elements (records) in bytes. 

• With an indexed file , you must specify information about the primary 
and any alternate keys. 


The value of the FORM parameter must be a VAX RMS File Definition 
Language (FDL) string, or it must be a reference to a file of FDL state¬ 
ments. 
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FDL is a special-purpose language that is written as an ordered sequence 
of file attribute keywords (sometimes called FDL statements) and their as¬ 
sociated values. These keywords and values determine the characteristics 
of external files. By using an FDL string (or a reference to a file of FDL 
statements) as the value of the FORM parameter in an CREATE or OPEN 
input-output operation, you can give your file any of the RMS attributes 
available in FDL, and you thereby supersede the default file attributes of 
your input-output package (see Section 2.3.3). 

If you are not familiar with FDL, you should read the Guide to VAX/VMS 
File Applications. It introduces FDL and shows how to design files using 
the EDIT/FDL Utility. The VAX/VMS File Definition Language Facility 
Reference Manual in the VAX/VMS Utilities Reference Volume gives com¬ 
plete information, including specific definitions of the FDL statements. 
The following sections summarize the FDL concepts and statements that 
you need to know to specify file attributes in VAX Ada FORM parameters 


2.3.1 The File Definition Language (FDL): Primary and Secondary Attributes 

FDL statements—whether in an FDL file or in a VAX Ada form string— 
specify predefined VAX RMS file attributes. Primary attributes take a single 
value or represent a group of related, or secondary , attributes, which also 
take values. (Most of the primary attributes that have secondary attributes 
do not themselves take a value.) Table 2-3 lists the available primary and 
secondary attributes. 


Table 2-3: FDL Primary and Secondary Attribute Descriptions 


Primary Function Secondary Attributes 

Attribute 


TITLE 

IDENT 


SYSTEM 


Primary attribute gives a title 
to the FDL file; for comment 
purposes only. 

Primary attribute gives the date 
and time of creation of the FDL 
file, and specifies the name of the 
creating utility (either EDIT/FDL 
or ANALYZE/RMS-FILE). 

Primary attribute takes no value. 
Secondary attributes give system 
identification information. 


None 


None 


DEVICE, SOURCE, TARGET 
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Table 2-3: (Cont.) FDL Primary and Secondary Attribute Descriptions 


Primary 

Attribute 

FILE 


Function 


Secondary Attributes 


Primary attribute takes no value. 
Secondary attributes determine 
file characteristics: its default 
name, owner, organization, 
protection, and revision; what 
will happen when it is opened 
or closed; whether or not data 
checking will be done when 
the file is read or written; what 
kind of processing is allowed; 
how much space is allocated for 
the file, and whether or not the 
space is contiguous; and so on. 
Secondary attributes also allow 
specification of magnetic tape file 
operations. 


ALLOCATION, 
BEST_TRY_CONTIGUOUS, 
BUCKET-SIZE, CLUSTER-SIZE, 
CONTEXT, CONTIGUOUS, 
CREATE—IF, DEFAULT-NAME, 
DEFERRED-WRITE, 
DELETE_ON_CLOSE, 
DIRECTORY-ENTRY, 

EXTENSION, 

GLOBAL_BUFFER_COUNT, 
MAXIMIZE—VERSION, 
MT_BLOCK_SIZE, 
MT_CLOSE_REWIND, 

MT_CURRENT—POSITION, 

MT_NOT_EOF, 

MT_OPEN_REWIND, 

MT_PROTECTION, 
MAX_RECORD_NUMBER, NAME, 
NON_FILE_STRUCTURED, 
ORGANIZATION, 
OUTPUT_FILE_PARSE, OWNER, 
PRINT_ON_CLOSE, 
PROTECTION, READ-CHECK, 
REVISION, SEQUENTIAL-ONLY, 
SUBMIT_ON_CLOSE, 
SUPERSEDE, TEMPORARY, 
TRUNCATE—ON_CLOSE, 
USER_FILE_OPEN, 
WINDOW-SIZE, WRITECHECK 
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Table 2-3: (Cont.) FDL Primary and Secondary Attribute Descriptions 


Primary 

Attribute 

DATE 


RECORD 


ACCESS 


SHARING 


CONNECT 


Function 


Secondary Attributes 


Primary attribute takes no value. 
Secondary attributes specify dates 
and times for backup, creation, 
expiration, and revision of the file. 
In general, the only secondary 
attribute that can be routinely 
and safely set is EXPIRATION; 
the others should be set by the 
system, and thus will not be 
useful or used in an Ada FORM 
parameter. 

Primary attribute takes no value. 
Secondary attributes specify 
the characteristics of records in 
the file: their size; the kind of 
carriage control; and their format. 

Primary attribute takes no value. 
Secondary attributes specify the 
file-processing operations allowed 
on the file. 

Primary attribute takes no value. 
Secondary attributes specify 
whether or not multiple readers 
or writers can concurrently access 
the file. 

Primary attribute takes no value. 
Secondary attributes specify 
run-time features and operations 
related to record access and 
performance. 


BACKUP, CREATION, 
EXPIRATION, REVISION 


BLOCK_SPAN, 

CARRIAGE-CONTROL, 

CONTROL-FIELD, 

FORMAT, SIZE 

BLOCK—IO, DELETE, GET, PUT, 
RECORD—IO, TRUNCATE, UPDATE 


DELETE, GET, MULTISTREAM, 
PROHIBIT, PUT, UPDATE, 
USER_INTERLOCK 


ASYNCHRONOUS, BLOCK-IO, 
BUCKET—IO, CONTEXT, 
END_OF_FILE, FAST—DELETE, 
FILL-BUCKETS, 
KEY_GREATER_EQUAL, 
KEY_GREATER_THAN, 
KEY-LIMIT, 
KEY_OF_REFERENCE, 
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Table 2-3: (Cont.) FDL Primary and Secondary Attribute Descriptions 

Primary Function Secondary Attributes 

Attribute 

LOCATE—MODE, LOCK_ON_READ, 
LOCK—ON_WRITE, 

MANUAL—UNLOCKING, 

MULTIBLOCK—COUNT, 

MULTIBUFFER_COUNT, NOLOCK, 

NONEXISTENT-RECORD, 

READ-AHEAD, 

READ_REGARDLESS, 

TIMEOUT-ENABLE, 

TIMEOUT-PERIOD, 

TRUNCATE_ON_PUT, 

TT_CANCEL_CONTROL_0, 

TT-PROMPT, 

TT_PURGE_TYPE_AHEAD, 

TT_READ_NOECHO, 

TT_READ_NOFILTER, 

TT_UPCASE_INPUT, 

UPDATE—IF, 

WAIT—FOR—RECORD, 
WRITE-BEHIND 

AREA Primary takes an integer value ALLOCATION, 

in the range 0 to 254, which BEST_TRY_CONTIGUOUS, 

identifies the area in an indexed BUCKET—SIZE, CONTIGUOUS, 

file. (Multiple areas must have a EXACT—POSITIONING, 

separate area defined for each.) EXTENSION, POSITION, 

Secondary attributes specify VOLUME 

characteristics of the area: how 

much space is allocated; whether 

or not the space is contiguous; 

positioning of the area; the 

volume on which the area will 

reside. 
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Table 2-3: (Cont.) FDL Primary and Secondary Attribute Descriptions 


Primary Function Secondary Attributes 

Attribute 


KEY Primary takes an integer value 

in the range 0 to 254, which 
gives the number of a key in 
an indexed file; the primary key 
number must be 0. 

Secondary attributes specify the 
characteristics of keys in the 
indexed file. 


ANALYSIS_OF_ Result of using ANALYZE/RMS- 

AREA FILE utility. Neither primary nor 

secondary attributes are useful in 
an Ada FORM parameter. 

ANALYSIS_OF_KEY Result of using ANALYZE/RMS- 

FILE utility. Neither primary nor 
secondary attributes are useful in 
an Ada FORM parameter. 


CHANGES, DATA_AREA, 

DATA—FILL, 

DATA_KEY_COMPRESSION, 
DATA_RECORD_COMPRESSION, 
DUPLICATES, INDEX—AREA, 
INDEX-COMPRESSION, 
INDEX-FILL, LENGTH, 

LEVEL1—INDEX—AREA, NAME, 
NULL-KEY, NULL-VALUE, 
POSITION, PROLOG, 
SEGn_LENGTH, 

SEGn_POSITION, TYPE 

RECLAIMED—SPACE 


DATA-FILL, 

DATA—KEY—COMPRESSION, 
DATA—RECORD—COMPRESSION, 
DATA_RECORD_COUNT, 

DATA—SPACE—OCCUPIED, 
DEPTH, 

DUPLICATES—PER—SIDR, 

INDEX-COMPRESSION, 

INDEX-FILL, 

INDEX_SPACE_OCCUPIED, 
LEVEL1—RECORD—COUNT, 
MEAN_DATA_LENGTH, 
MEAN_INDEX_LENGTH 


When using FDL to specify the attributes of an Ada external file, you 
should observe the following FDL rules. (Note that any FDL errors 
occurring in a FORM parameter will raise the predefined exception 
USE-ERROR.) 

• The primary attributes must appear in the order shown in Table 2-3. 
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• Each attribute string (primary or secondary) constitutes an FDL state¬ 
ment, and must be terminated with a semicolon. For example: 

-- Create SOME_FILE.DAT with fixed record format and 
-- record size of 120 bytes 
CREATE(FILE => MY_FILE, 

MODE => 0UT_FILE, 

NAME => "S0ME_FILE.DAT", 

FORM => "RECORD; FORMAT FIXED; SIZE 120;"); 

Note that the exclamation point is the comment character in FDL, and 
anything following it is ignored. For example: 

-- Create S0ME_FILE.DAT with fixed record format 


CREATE(FILE => MY_FILE, 

MODE => 0UT_FILE, 

NAME => "S0ME_FILE.DAT", 

FORM => "RECORD; FORMAT FIXED; !fixed-size records"); 

• Each FDL statement can represent only one primary or secondary 
attribute and its associated value. Each statement can have no more 
than a total of 132 characters (including blanks). To format your 
program without adding extra blanks to the form string, you can use 
the Ada concatenation operator (ampersand) to break up the form 
string into individual statements strings. Thus, the preceding example 
could be rewritten as 


CREATE(FILE => 
MODE => 
NAME => 
FORM => 


MY.FILE, 

OUT.FILE, 

"S0ME_FILE.DAT", 

"RECORD;" 

"FORMAT FIXED;" 
"SIZE 120;" 


& 

& 

); 


• If you are working with an indexed file that has two or more AREA 
primary attributes, they must follow one another in numerical order. 

• If you are working with an indexed file that has two or more KEY 
primary attributes, they must follow one another in numerical order. 

In addition, any SEGn secondary attributes must follow one another 
in numerical order, and the SEGn numbers must be "dense". That is, 
if you use SEG3 to label a key segment, segments SEGO, SEG1, and 
SEG2 must also exist. 

• Keywords can be truncated to their shortest unique abbreviations, and 
strings must be enclosed either in a pair of apostrophes or a pair of 
double quotation marks. Note that Ada based integers or integers with 
underscores are not legal FDL syntax. 
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In addition to allowing you to specify file attributes directly in a form 
string, VAX Ada also allows you to give a reference to an FDL file using a 
VAX/VMS file specification. The specification must be preceded by an at 
sign ((a)). For example: 

— Create SOME_FILE.DAT with specifications declared in 
-- the FDL file FILE.ATTRIBUTES.FDL. 

CREATE(FILE => MYJFILE, 

MODE => OUT.FILE, 

NAME => "SOME_FILE.DAT", 

FORM => "@FILE_ATTRIBUTES.FDL"); 

An advantage of being able to give an FDL file reference is that you can 
use the EDIT/FDL Utility to construct the FDL file. The utility is designed 
to help you choose file attributes that will help optimize the efficiency of 
your program. In particular, the utility is helpful in tuning indexed files. 
For example, it can plot graphs to help you determine appropriate bucket 
sizes for specific indexed files. See the Guide to VAX/VMS File Applications 
for more information on the EDIT/FDL utility and file design. 

Table 2-4 describes the primary and secondary FDL attributes that you 
would be most likely to use in a VAX Ada program, and gives their 
default values. The intent of the table is to provide a quick reference 
and to summarize information presented in the VAX/VMS File Definition 
Language Facility Reference Manual ; see that manual for details. 

As shown in the table, the value assigned to an attribute can take one of 
the following forms: 

Switch A logical value, set to TRUE, YES, FALSE, or NO. TRUE 

(or YES) sets the attribute; FALSE (or NO) clears it. (You 
can also use the abbreviations T, Y, F, and N for TRUE, 
FALSE, YES, and NO.) 

Keyword An actual word that you must type (in either upper or 

lowercase) after the attribute name. You can truncate a 
keyword to its shortest unique abbreviation. 

String A character string (enclosed in either a pair of apostrophes 

or a pair of double quotation marks) that you must type 
after the attribute name. The null string is a valid string 
value. Note that to use double quotation marks in the 
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same statement, you would have to write the form string 
following Ada conventions: 

CREATE(FILE => F, 

MODE => OUT.FILE, 

FORM => "FILE;" k 

"DEFAULT.NAME ""SOME_FILE.DAT"";" k 


-- a pair of quotation marks 
-- inside a string represents 
-- one quotation mark 
"RECORD;" k 

"FORMAT FIXED;" k 

"SIZE 100;" ); 

Use of apostrophes is thus more elegant: 

CREATE(FILE => F, 

MODE => OUT.FILE, 

FORM => "FILE;" k 

"DEFAULT.NAME 'SOME.FILE.DAT';" k 

"RECORD;" k 

"FORMAT FIXED;" k 

"SIZE 100;" ); 


Integer A decimal integer (based integers or underscores are not 

allowed). 


Table 2-4: Commonly Used FDL Attributes 


FDL Attributes 

Type of Value and 

Default 

Function 

TITLE 

String of up to 132 char¬ 
acters including the TITLE 
keyword. 

No default value. 

Comment (names the file). 

IDENT 

String of up to 132 charac¬ 
ters including the IDENT 
keyword. 

Default value is the date, 
time of creation, name 
of creating utility if cre¬ 
ated with EDIT/FDL or 
ANALYZE/RMS-FILE; 
otherwise, no default value. 

Record identifying file information. 

SYSTEM 

DEVICE 

String. 

Default value is null. 

Comment (names the disk model on 
which the file will reside). 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


FILE 

ALLOCATION 


BEST—TRY— 

CONTIGUOUS 


BUCKET-SIZE 


CONTIGUOUS 


DEFAULT-NAME 


Type of Value and Function 

Default 


Integer in the range 0 to 
4294967295. 

Default value is 0. 

Switch. 

Default value is NO. 


Integer in the range 0 to 63. 
Default value is 0. 


Switch. 

Default value is NO. 


String. 

Default value is null. 


Sets the number of blocks that will be 
initially allocated for the file. If 0, the 
system will not preallocate space for 
the file. 

Controls whether the file will be 
allocated contiguously if there is 
enough space for it. If set to YES, and 
there is enough space for the file, the 
file will be allocated contiguously; if 
there is not enough space, the file will 
not be allocated contiguously. If set to 
NO, this attribute is ignored. 

Sets the number of blocks per bucket. 
If 0, VAX RMS computes the bucket 
size to be the smallest bucket size 
capable of holding the largest record. 

Controls whether the file must be 
allocated contiguously. When set to 
YES and there is not enough space 
for the file's initial allocation, an error 
message results. When set to NO, the 
attribute is ignored. 

Uses its string value to define portions 
of the file specification of the file to be 
created. If you supply only a partial 
file specification in the NAME pa¬ 
rameter to an Ada OPEN or CREATE 
operation, the DEFAULT—NAME 
value is used for the missing part 
of the file specification. If you have 
not specified a value for DEFAULT- 
NAME, the VAX RMS defaults are 
used for the missing part. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


EXTENSION 


MAX_RECORD_ 

NUMBER 


ORGANIZATION 


PRINT_ON_CLOSE 


PROTECTION 


Type of Value and Function 

Default 


Integer in the range 0 to 
65535. 

Default value is 0. 


Sets the number of blocks for the 
default extension value for the file. 
Each time the file is extended, the 
specified number of blocks is added. If 
0, the extension size is determined by 
the system each time the file must be 
extended. 


Integer in the range 0 to 
2147483647. 

Default value is 0. 


Specifies the maximum number of 
records that can be placed in a relative 
file. If 0, then you can place as many 
records as you want in the file, up to 
2,147,483,647. 


Keyword. Defines the type of file organiza- 

Default value is SEQUENTIAL, tion. Must be one of the key¬ 
words SEQUENTIAL, RELATIVE, 
or INDEXED. 


Switch. Controls whether the data file is to be 

Default value is NO. spooled to the process default print 

queue (SYS$PRINT) when the file is 
closed. When set to YES, the data 
file is spooled; when set to NO, the 
attribute is ignored. (This attribute 
applies to sequential files only.) 

String. Defines the levels of file protection for 

Default value is the process the file. Its value can take one of two 
default. forms (SYSTEM=code, OWN=code, 

GROUP=code, WORLD=code) 
or (SYSTEM:code, OWN:code, 
GROUP:code, WORLD:code) where 
the code is a protection specification 
for READ, WRITE, EXECUTE, and 
DELETE in the form RWED. To deny 
a specific access right, you omit it from 
the code. To give no access rights 
to a user classification, you omit the 
classification from the list. 


Input-Output Facilities 2-19 


Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


SEQUENTIAL 


SUBMIT—ON 


DATE 

EXPIRATION 


RECORD 

CARRIAGE- 

CONTROL 


Type of Value and Function 

Default 


.ONLY Switch. 

Default value is NO 


CLOSE Switch. 

Default value is NO. 


For example, the following string 
gives all access rights to SYSTEM and 
OWNER, gives only READ access 
to GROUP, and gives no access 
rights to WORLD: (SYSTEM=RWED, 
OWNER=RWED, GROUP=R). 

Indicates that the file can only be 
processed sequentially, thus allowing 
certain processing optimizations. Any 
attempt to perform random access 
results in an error. 

Determines whether the data file is 
submitted to the process batch queue 
(SYS$BATCH) when the file is closed. 
When set to YES, the data file is 
submitted to the batch queue; this 
setting makes sense only if the file 
is a command file with sequential 
organization. When set to NO, this 
attribute is ignored. 


String in the form Sets the date and time after which a 

dd-mm-yyyy hh:mm:ss.cc. disk file can be considered for deletion. 
Default value is null. For magnetic tape files, this attribute 

sets the date and time after which you 
can overwrite the file. This is the only 
DATE secondary attribute that you can 
routinely and safely set. 


Keyword. Specifies the type of carriage control 

Default value is CARRIAGE— for the records in the file. Must be 
RETURN. one of the keywords CARRIAGE- 

RETURN, FORTRAN, NONE, or 
PRINT. See Section 2.6.5.3 of this 
manual and the VAX/VMS File 
Definition Language Facility Reference 
Manual for more information. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


FORMAT 


SIZE 


Type of Value and Function 

Default 

Keyword. Sets the record format for the data file. 

Default value is VARIABLE. Must be one of the keywords FIXED, 

STREAM, STREAM_CR, STREAM— 
LF, UNDEFINED, VARIABLE, VFC. 

See the VAX/VMS File Definition 
Language Facility Reference Manual for 
more information. 

Integer. Sets the maximum record size in bytes. 

No default value. With fixed-length records, this value 

is the length of every record in the 
file. With variable-length records, 
this value is the length of the longest 
record that can be placed in the file. 

If the file has sequential or indexed 
organization, you can specify 0 and the 
system will not impose a maximum 
record length. The records in an 
indexed file, however, cannot cross 
bucket boundaries. 

If the file has relative organization, 
the SIZE attribute is used with the 
BUCKET—SIZE attribute to set the size 
of the fixed-length cells. 

If the records are variable with fixed 
control (VFC), the fixed control portion 
of the record is not included in 
the SIZE calculation; only the data 
portion is set by this attribute. The 
fixed area is the size in bytes of the 
fixed-control portion of VFC records. 
Regular variable-length records have 
a fixed-control size of 0. See the 
VAX/VMS File Definition Language 
Facility Reference Manual for the 
maximum sizes allowed for the various 
record organizations and formats. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 

Type of Value and 

Default 

Function 

ACCESS 

DELETE 

Switch. No default value. 

Permits VAX RMS delete operations. 

GET 

Switch. 

Default value is GET when 
using an OPEN procedure 
and if no other ACCESS 
secondary attribute has been 
specified and SHARING 
DELETE or SHARING 
UPDATE have been speci¬ 
fied. 

Permits VAX RMS get or find opera¬ 
tions. 

PUT 

Switch. 

PUT when using a CREATE 
procedure. 

Permits VAX RMS put or extend 
operations. 

TRUNCATE 

Switch. 

Default value is FALSE. 

Permits VAX RMS truncate operations. 

UPDATE 

Switch. 

Default value is FALSE. 

Permits VAX RMS update or extend 
operations. 

SHARING 

DELETE 

Switch. 

No default value. 

Allows other users to delete records 
from the file. 

GET 

Switch. 

TRUE if ACCESS GET has 
also been specified. 

Allows other users to read the file. 

PROHIBIT 

Switch. 

YES if ACCESS DELETE, 
ACCESS PUT, ACCESS 
TRUNCATE, or ACCESS 
OPERATE has been speci¬ 
fied. 

Prohibits any type of file sharing by 
other users. When set to YES, this 
attribute takes precedence over all 
other ACCESS secondary attributes. 

PUT 

Switch. 

No default value. 

Allows other users to write records to 
the file. 

UPDATE 

Switch. 

No default value. 

Allows other users to update records 
that currently exist in the file. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


CONNECT 

MULTIBUFFER_ 

COUNT 


READ-AHEAD 


TIMEOUT-ENABLE 


Type of Value and Function 

Default 


Integer in the range -128 to 
127. 

No default value. 


Switch. 

No default value. 


Switch. 

No default value. 


Specifies the number of buffers 
to be allocated when the file is 
opened. If the value is not set or 
0, VAX RMS chooses a default value 
(see the VAX/VMS File Definition 
Language Facility Reference Manual). 
This attribute is ignored for DECnet 
operations. 

Indicates read-ahead operations; to 
be used with multiple buffers. When 
one buffer is filled, the next record 
is read into the next buffer while 
the input-output operation takes 
place for the first buffer. Since the 
system does not have to wait for 
input-output completion, input and 
computing can overlap. This attribute 
is ignored for DECnet operations. See 
the VAX/VMS File Definition Language 
Facility Reference Manual for more 
information. 

Specifies that the maximum time, in 
seconds, will be allowed for a record 
input wait (see TIMEOUT-PERIOD). 
The input wait can be caused by a 
locked record if the WAIT—FOR— 
RECORD attribute has also been 
specified, or it can be caused by 
the input of a character from the 
terminal. If the timeout period expires, 
VAX RMS returns an error status. 

This attribute is ignored for DECnet 
operations. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


TIMEOUT-PERIOD 


TRUNCATE-ON- 

PUT 


UPDATE—IF 


WAIT—FOR—RECORD 


Type of Value and Function 

Default 


Integer in the range 0 to 
255. 

No default value. 


Switch. 

No default value. 


Switch. 

No default value. 


Switch. 

No default value. 


Specifies the maximum number of 
seconds that a VAX RMS get operation 
can take; if the operation is specified 
from the terminal and you specify 0, 
the current contents of the type ahead 
buffer are returned. You must use the 
TIMEOUT-ENABLE attribute with 
TIMEOUT-PERIOD. This attribute is 
ignored for DECnet operations. 

Specifies that a VAX RMS put or write 
operation can occur at any point in a 
file, truncating the file at that point. A 
write operation causes the end of file 
mark to immediately follow the last 
byte written. This attribute can only 
be used with VAX RMS sequential 
files. 

Indicates that if a put operation is 
specified for a record that already 
exists in the file, the operation is 
converted to an update. This attribute 
is necessary to overwrite (as opposed 
to update) an existing record in VAX 
RMS relative and indexed sequential 
files. Indexed files using this attribute 
must not allow duplicates on the 
primary key. 

Specifies that VAX RMS should wait 
for a currently locked record until it 
becomes available. You can use this 
attribute with the TIMEOUT-ENABLE 
and TIMEOUT—PERIOD attributes to 
limit waiting periods to a specified 
time. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 

WRITE_BEHIND 


AREA 

KEY 

CHANGES 

DATA_KEY_ 

COMPRESSION 


Type of Value and Function 

Default 


Switch. Indicates that write-behind operations 

No default value. are to occur when multiple buffers 

are used. When one buffer is filled, 
the next record is written into the 
next buffer while the input-output 
operation takes place for the first 
buffer. Since the system does not have 
to wait for input-output completion, 
computing and output can overlap. 

See the VAX/VMS File Definition 
Language Facility Reference Manual for 
more information. 


This attribute and its secondaries apply only to files with indexed 
organization. See the VAX/VMS File Definition Language Facility 
Reference Manual for details. 


Integer in range 0 to 254. 
No default value. 


Switch. 

Default value is NO. 


Switch. 

Default value is YES. 


Denotes the key number for a file with 
indexed organization. The value for 
the primary key must be 0; the value 
for alternate keys can be any integer 
in the range 1 to 254. This attribute 
and its secondaries apply only to files 
with indexed organization. 

Determines whether or not key values 
can be changed with a VAX RMS 
update operation. Note that a value of 
YES primary keys is an error; a value 
of YES for alternate keys is allowed. 

Controls whether leading and trailing 
repeating characters in the primary key 
will be compressed. For compression 
to occur, your indexed file should 
be defined as a Prolog 3 file with 
the FDL attributes KEY PROLOG; 

KEY PROLOG 3 is the default. This 
attribute must be set for indexed files 
involved in DECnet operations. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


DATA_RECORD_ 

COMPRESSION 


DUPLICATES 


INDEX_COMPRESSION 


LENGTH 


NAME 


Type of Value and Function 

Default 


Switch. 

Default value is YES. 


Switch. 

Default value is NO for 
the primary key; YES for 
alternate keys. 


Switch. 

Default value is YES. 


Integer. 

No default value. 


String of from 1 to 32 
characters. 

Default value is null. 


Controls whether repeating characters 
are compressed in file records. For 
compression to occur, your indexed 
file must be defined as a Prolog 3 file 
with the FDL attributes KEY PROLOG; 
KEY PROLOG 3 is the default. This 
attribute should be set for indexed files 
involved in DECnet operations. 

Controls whether duplicate keys 
are allowed in files with indexed 
organization. When set to YES, this 
attribute specifies that there can be 
more than one record with the same 
specific key value. When set to NO, 
duplicate keys are not allowed, and 
any attempt to write a record where 
the key would be a duplicate will 
result in an error. 

Controls whether leading repeating 
characters in the index are compressed. 
For compression to occur, your in¬ 
dexed file should be defined as a 
Prolog 3 file with the FDL attributes 
KEY PROLOG; KEY PROLOG 3 is 
the default. This attribute must be set 
for indexed files involved in DECnet 
operations. 

Sets the length of the key in bytes. 
This value, along with the POSITION 
and TYPE attributes, is used when 
the key is unsegmented. Note that 
because there is no default, this value 
must be specified. 

Assigns a name to a key. This value is 
optional. Note that the specified string 
is padded with ASCII null characters 
to a length of 32 bytes. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 


NULL_VALUE 


POSITION 


PROLOG 


Type of Value and Function 

Default 


Character or unsigned 
decimal integer representing 
ASCII value. 

Default value is the ASCII 
null character (0). 


Integer. 

No default value. 


Integer in the range 1 to 3. 
Default value is 3. 


Defines the null value that will instruct 
the system not to create an alternate 
index entry for the record that has 
the null value in every byte of the 
key field. If the alternate key is of 
type STRING, you can specify the 
null value by either specifying the 
character itself or by specifying an 
unsigned decimal number denoting the 
character's ASCII value. To specify the 
character, enclose it in apostrophes; to 
specify the decimal ASCII value, type 
it without enclosing apostrophes. 

Defines the byte position of the 
beginning of the key field within the 
record. The first position is 0; primary 
keys work best if they start at byte 
0. This attribute, along with the KEY 
LENGTH and TYPE attributes, is used 
when the key is unsegmented. 

Defines the internal structure of a file 
with indexed organization. See the 
VAX/VMS File Definition Language 
Facility Reference Manual for details. 
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Table 2-4: (Cont.) Commonly Used FDL Attributes 


FDL Attributes 

Type of Value and 

Default 

Function 

SEGn_LENGTH 

Integer in the range 0 to 7. 
No default value. 

Defines the length of the key segment 
in bytes. This attribute is used with 
the SEGn_POSITION attribute when 
the key is segmented. The "n" is 
the number of the segment and may 
be numbered from 0 to 7; the first 
segment must be numbered 0. Note 
that segmented keys must be of type 
STRING, and segments may not 
overlap for Prolog 3 files. 

SEGn_POSITION 

Integer. 

No default value. 

Defines the key segment's starting 
position within the record. The first 
position is 0. Note that segmented 
keys must be of type STRING, and 
segments may not overlap for Prolog 3 
files. 

TYPE 

Keyword. 

Default value is STRING. 

Defines the type of the key. May 
have any of the following values: 

BIN2, BIN4, BIN8, INT2, INT4, INT8, 
STRING. See the VAX/VMS File 
Definition Language Facility Reference 
Manual for more information. 


Certain FDL attributes can significantly improve application performance. 
That is, if the files used by the application are designed and tuned prop¬ 
erly, the application will run more efficiently, often because a minimum 
number of input-output operations occur. File design and tuning are 
important for large files, especially indexed files. The file characteris¬ 
tics specified when a file is created often have a significant effect on 
application performance at run time. 

Among the FDL attributes listed in Table 2-4, the following can affect 
application performance: 

FILE ALLOCATION 

FILE BEST_TRY_CONTIGUOUS 

FILE BUCKET-SIZE 

FILE CONTIGUOUS 

FILE EXTENSION 

CONNECT READ-AHEAD 
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CONNECT WRITE—BEHIND 
ACCESS and SHARING attributes 
certain KEY attributes 


Other attributes not listed that can affect performance include 

FILE DEFERRED_WRITE 
CONNECT FAST_DELETE 
CONNECT GLOBAL_BUFFER_COUNT 
CONNECT MULTIBLOCK_COUNT 
CONNECT MULTIBUFFER_COUNT 
FILE SEQUENTIAL_ONLY 
FILE WINDOW—SIZE 

For additional information, refer to the Guide to VAX/VMS File 
Applications. 


2.3.2 Creation-Time and Run-Time Attributes 

Of the many attributes that may be associated with an external file, 
some exist as long as the external file exists. These are called creation¬ 
time attributes. The remainder, the run-time attributes, exist only as 
long as the external file is associated with a particular file object; that is, 
they can change dynamically at run time, and must be respecified each 
time the file is opened. Examples of creation-time attributes are FILE 
ORGANIZATION and RECORD SIZE; examples of run-time attributes are 
any of the attributes secondary to the primary CONNECT, ACCESS, or 
SHARING attributes, as well as the FILE secondary attribute PRINT_ON_ 
CLOSE. The Guide to VAX/VMS File Applications identifies all creation¬ 
time and run-time attributes and discusses them in more detail. 

You can change a file's creation-time characteristics only by creating or 
recreating the file. Inside of an Ada program, you can give creation-time 
attributes to the external file with a CREATE operation; these attributes 
are then inherited by the file in subsequent OPEN operations. Outside 
of an Ada program, you can change the creation-time characteristics of 
an external file by using the EDIT/FDL and Convert or Convert/Reclaim 
Utilities to create a new external file and populate it with elements of the 
old file. 

If you specify any creation-time file attributes in an OPEN operation, they 
are considered merely to be assertions; they do not affect the external 
file's characteristics. VAX Ada protects you from making wrong assertions 
of creation-time attributes in an OPEN operation. If you specify a value 
for FORM in an OPEN procedure call, the OPEN operation checks the 
following creation-time attributes of the external file against any assertions 
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of those attributes in the FORM string value, and the exception 
USE_ERROR is raised if there is a mismatch: 

• the FILE secondary attribute ORGANIZATION. 

• the RECORD secondary attribute CARRIAGE_CONTROL. 

• the RECORD secondary attribute FORMAT. 

• the RECORD secondary attribute SIZE. 

• every KEY section (in an indexed file). 

For example, if an FDL string for FORM asserts that the organization of 
the external file is indexed, but the external file being opened is actually 
sequential, USE_ERROR is raised. Note that if no creation-time-attribute 
assertions are made, no check is done. 


2.3.3 Default External File Attributes 

When a file is opened (either by a CREATE or an OPEN procedure), the 
input-output package being used provides a set of default external file 
attributes. One purpose of the default attributes is to allow the program 
to pass a null form string (the default) to an OPEN procedure and still 
open the external file. Thus, no form string is required when you use an 
OPEN procedure to open a file, but in some situations certain external 
file attributes must be specified when a CREATE procedure is called (see 
Section 2.3). 

A table of default attributes is given for each package in the section 
describing the use of that package (see Tables 2-5 through 2-13 in 
Sections 2.6.1 through 2.6.5). However, three points should be noted 
here. First, if any creation-time attributes are specified in the FORM pa¬ 
rameter of an OPEN procedure, they have no effect, except to cause a 
consistency check against the creation-time attributes that already exist for 
the file (see Section 2.3.2). Second, there are many FDL default attributes 
that are automatically applied that are not shown in the default attribute 
tables; see the VAX/VMS File Definition Language Facility Reference Manual 
for the FDL defaults. Third, input-output packages impose certain restric¬ 
tions on the attributes of the external files that they open. If the file is 
being created, these restrictions are checked against any external file char¬ 
acteristics given in the FORM parameter of the CREATE procedure. If the 
file is being opened, the restrictions are checked after any assertions in the 
FORM parameter of the OPEN procedure have been checked against the 
existing attributes of the file. If the restrictions are violated at either point, 
the exception USE_ERROR is raised. The restrictions for each package are 
discussed in Sections 2.6.1 through 2.6.5. 
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2.4 File Sharing 


File sharing in VAX Ada enables concurrent access to the same external 
file. In other words, file sharing permits multiple file objects to be associ¬ 
ated with the same external file, in the same VAX/VMS process or across 
multiple processes. External files may be shared for reading, writing, or 
modification. You should note, however, that because VAX Ada files are 
layered on RMS file organizations, the rules that apply to read and write 
sharing of RMS files also apply to Ada files. Files with RMS sequential file 
organization are normally not write shareable; however, files of any RMS 
file organization can be read shared. Refer to the Guide to VAX/VMS File 
Applications for a complete description of file sharing for files of different 
organizations. 

The FDL ACCESS and SHARING primary attributes control the scope 
of access and sharing of an external file. The ACCESS primary attribute 
specifies whether read, write, or modification operations may be performed 
on the external file; the SHARING primary attribute also specifies the kind 
of operations allowed for concurrent openings of the same file. 

When a file is opened, VAX Ada uses the MODE parameter to select 
appropriate default ACCESS and SHARING secondary attributes (see 
Section 2.3.3 and Tables 2-5 through 2-13). If the FORM parameter 
in the OPEN procedure specifies values for the ACCESS or SHARING 
attributes, those values supersede the selected defaults. 

The SHARING attributes are ignored for record-oriented devices and 
magnetic tape files that are mounted foreign. For ANSI magnetic tape 
files, a concurrent OPEN operation raises the exception USE_ERROR, 
even though a SHARING attribute may be specified in the initial OPEN 
operation. The number of shared files is restricted by the system-wide 
shared-file database. 


By specifying PROHIBIT as the value of the SHARING attribute in the 
FORM parameter, you can deny any kind of access to concurrently 
executing users when you first open the external file. To do so, however, 
you must have write access to the file. For example: 


DIRECT_I0.OPEN(FILE => 
NAME => 
MODE => 
FORM => 


MY_FILE, 

"FILE.DAT", 
INOUT.FILE, 
("ACCESS;" & 

"PUT;" & 

"SHARING;" & 

"PROHIBIT")); 
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Here the OPEN operation specifies PUT for access, but PROHIBIT for 
sharing. After the external file, FILE.DAT, is opened, the file object, 
MY_FILE, can be used in any operations available in the package 
DIRECT—IO that result only in writing of the external file. Operations 
that result in any other record operations to FILE.DAT will raise the ex¬ 
ception USE_ERROR. Concurrent attempts to open FILE.DAT will also 
raise USE-ERROR. 

In any attempt to open an external file that has already been opened, the 
value of the ACCESS attribute must match the value of the SHARING 
attribute given to the file when it was first opened (or created), and the 
value of the SHARING attribute must match the value of the ACCESS 
attribute given to the file when it was first opened (or created). Otherwise, 
the attempt to open the external file will raise the exception USE—ERROR. 


Note that although write sharing is allowed for relative and indexed 
files, you can improve the performance of your program if you avoid write 
sharing. See the Guide to VAX/VMS File Applications for more information. 


2.5 Record Locking 

The VAX RMS record locking facility allows more than one program 
to concurrently add, delete, or update a VAX RMS record in a con¬ 
trolled manner. Record locking is available to external files in the same 
VAX/VMS process and across different processes. 

In VAX Ada, record locking is provided only for relative and indexed 
files (see Tables 2-9 through 2-12 in Sections 2.6.3 and 2.6.4). When one 
of these files is opened, and the attributes SHARING GET, SHARING 
PUT, or SHARING UPDATE are specified in the FORM parameter, VAX 
RMS locks each record as it is accessed. The same external file may then 
be reopened and associated with another Ada file according to the kind 
of sharing specified. When a record of an external file is locked as the 
result of an operation on a particular Ada file, any other operation on 
another Ada file that attempts to access the same record will fail, and the 
exception LOCK—ERROR is raised. A subsequent read, write, modify, 
or delete record operation of the original Ada file unlocks the previously 
locked record. Refer to Chapter 14 of the VAX Ada Language Reference 
Manual for descriptions of the effects of these operations on the locking 
and unlocking of elements in Ada relative and indexed files. 
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2.6 Using the VAX Ada Input-Output Packages 


VAX Ada provides three kinds of input-output packages. One kind— 
SEQUENTIAL _IO, DIRECT-IO, RELATIVE_IO, and INDEXED_IO— 
allows you to work with binary files containing elements that are all of 
the same type (a file of elements of an integer type, a file of elements 
of a record type, a file of elements of an array type, and so on). These 
packages are all generic; you must instantiate them with the type of the 
elements in the file before you can use their operations. 

A second kind—SEQUENTIAL_MIXED_IO, DIRECT_MIXED_IO, 
RELATIVE_MIXED_IO, and INDEXED_MIXED_IO—allows you to 
work with binary files of mixed types. For example, you could have a 
mixed-type file that contains elements of three different integer types, or a 
file that contains elements that are a mixture of integer types, array types, 
string types, and so on. The mixed-type packages are nongeneric, but they 
involve buffer operations that are generic. For example, you must instan¬ 
tiate GET—ITEM and PUT—ITEM operations in order to move values in 
and out of a buffer; you then read or write the buffer in order to transfer a 
record to or from your file. Figure 2-1 illustrates the use of a mixed-type 
file (using the package DIRECT_MIXED_IO); Figure 2-2 illustrates the 
use of a file with elements of the same type (using the package 
DIRECT—IO). 

The third type of package—TEXT_IO—allows you to work with files 
of human-readable characters. TEXT—IO is not generic, but it includes 
generic packages for the input and output of integers, floating-point and 
fixed-point numbers, as well as a generic package for the input and output 
of enumeration values. 

Sections 2.1.1 through 2.1.5 describe the structure of VAX Ada files and 
give their relationship to RMS files; Chapter 14 of the VAX Ada Language 
Reference Manual describes the packages and their operations in more 
detail. The following sections give additional information (including 
default file attributes) and present examples that illustrate the features 
of each kind of package. If you are interested in information about 
designing files and tuning them for optimum performance, see the Guide 
to VAX/VMS File Applications. 
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Figure 2-1: Using a Mixed-Type File 


with DIRECT_MIXED_10; 

use DIRECT_MIXED_10; 

procedure EXPENSE_ACCOUNT is 

type AMOUNT is delta 0,01 range 0.00..5000.00; 

subtype DATE_TYPE is STRING (1..8); 

COUNT: NATURAL :=0; 

procedure PUT_DATE is new PUT_ITEM (DATE_TYPE); 

procedure PUT_COUNT is new PUT_ITEM (NATURAL); 
procedure PUT_COST is new PUT_ITEM (AMOUNT); 

procedure GET_DATE is new GET_ITEM (DATE_TYPE); 

procedure GET_COUNT is new GET_ITEM (NATURAL); 

procedure GET_COST is new GET_ITEM (AMOUNT); 


EXPENSES: FILE_TYPE; 

begin 

CREATE (FILE => EXPENSES, 

MODE => INOUT_FILE; 

NAME => “EXPENSES.DAT”, 

FORM => “RECORD;” & 

“FORMAT FIXED;” & 
“SIZE 32;”); 

PUT_DATE (EXPENSES, “01-08-84”); O 

WRITE (EXPENSES,1); © 

PUT__COST (EXPENSES, 0.80); © 

COUNT := COUNT+1; 

PUT_COST (EXPENSES, 27.95); O 

COUNT := COUNT+1; 

PUT_COST (EXPENSES, 35.00); © 

COUNT := COUNT+1; 

WRITE (EXPENSES,3); © 

PUT_COUNT (EXPENSES, COUNT); O 

WRITE (EXPENSES,2); © 

RESET (EXPENSES); 

READ (EXPENSES,2); © 

GET_COUNT (EXPENSES, COUNT); © 

CLOSE (EXPENSES); 

end; 
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Figure 2-1 (Cont.): Using a Mixed-Type File 


O File EXPENSES: 
Buffer (32-byte): 

© File EXPENSES 
Buffer (32-byte): 

© File EXPENSES 

Buffer (32-byte): 

O File EXPENSES 
Buffer (32-byte): 

© File EXPENSES 
Buffer (32-byte): 

© File EXPENSES 
Buffer (32-byte): 

© File EXPENSES 
Buffer (32-byte): 

© File EXPENSES 
Buffer (32-byte): 

© File EXPENSES 

Buffer (32-byte): 
0 COUNT 3. 
Buffer is empty. 
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Figure 2-2: Using a Uniform-Type File 


with DIRECT_10; 

procedure POWERS_OF_TEN is 

package TEN__IO is new DIRECT^IO (NATURAL); 

use TEN_10; 

TEN: NATURAL : 10; 

POWER: NATURAL; 

TEN_FILE: FILE_TYPE; 

begin 

CREATE (TEN_FILE, INOUT__FILE, “TEN_FILE.DAT”); 

for POWER in 0..5 loop 

WRITE (TEN_FILE, TEN* *POWER); 

end loop; 

RESET (TEN_FILE); 

READ (TEN_FILE, TEN, 3); 

end POWERS_OF_TEN; 


element 


(index) 

1 

2 

3 

4 

5 

State of TEN_FILE 

at end of loop: 

1 

10 

100 

1000 

10000 


Element read 

by READ statement: TEN=100 
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2.6.1 Using Sequential Files 

For creating and working with sequential files of uniform-type elements, 
VAX Ada provides the generic package SEQUENTIAL_IO; for creating 
and working with sequential files of mixed-type elements, VAX Ada 
provides the nongeneric package SEQUENTIAL_MIXED_IO. 

When you create a file with either of these packages, the file will have 
the default file attributes listed in Table 2-5 Or Table 2-6. You can use 
SEQUENTIAL_IO and SEQUENTIAL_MIXED_IO to open and read files 
of any VAX RMS organization. 
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Table 2-5: SEQUENTIAL-JO: Default File Attributes 


File Attributes 

Default Value 

FILE 

ORGANIZATION 

SEQUENTIAL 

SEQUENTIAL_ONLY 

YES 

RECORD 

CARRIAGE—CONTROL 

CARRIAGE-RETURN 

FORMAT 

FIXED if ELEMENT-TYPE is constrained; 
VARIABLE if unconstrained 

SIZE 

(ELEMENT—TYPE'MACHINE—SIZE 
+ 7)/8 if ELEMENT—TYPE is constrained; 

0 (unlimited) if not (note, however, that 
there are physical limitations to SIZE; see 
the VAX/VMS Record Management Services 
Reference Manual) 

ACCESS 

GET 

YES 

PUT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

TRUNCATE 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN-FILE; 

NO if MODE is OUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

CONNECT 

TRUNCATE—ON-PUT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 
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Table 2-6: SEQUENTIAI_MIXED—IO: Default File Attributes 


File Attribute 

Default Value 

FILE 


ORGANIZATION 

SEQUENTIAL 

SEQUENTIAL-ONLY 

YES 

RECORD 


CARRIAGE-CONTROL 

CARRIAGE-RETURN 

FORMAT 

VARIABLE 

SIZE 

0 (record size is unlimited; note, however, 
that SIZE has physical limitations; see 
the VAX/VMS Record Management Services 
Reference Manual) 

ACCESS 


GET 

YES 

PUT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

TRUNCATE 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

SHARING 


GET 

YES if MODE is IN-FILE; 

NO if MODE is OUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

CONNECT 


TRUNCATE_ON_PUT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

Example 2-1 shows how to instantiate the package SEQUENTIAL_IO, as 
well as how to open, close, read, and write from an Ada sequential file. 

Example 2-1: Using Package SEQUENTIAL—IO 


with SEQUENTIAL.IO; 
procedure SHOW_SEQ is 

type STRING_TYPE is new STRING(1..10); 

package INOUT.STRING is new SEQUENTIAL_I0(STRING.TYPE); 

use INOUT.STRING; 

STRING_FILE : FILE_TYPE; 

STRING.VAR : STRING.TYPE; 


2-38 


Input-Output Facilities 




Example 2-1 (Cont.): Using Package SEQUENTIAI_IO 


begin 


-- write a string to STRINGDAT.DAT 

CREATE(FILE => STRING.FILE, 

MODE => OUT_FILE, 

NAME => "STRINGDAT.DAT"); 
WRITE (STRING.FILE, "tenletters"); 
CLOSE (STRING.FILE); 


-- read a string from the same file 

OPEN (FILE => STRING.FILE, 

MODE => IN_FILE, 

NAME => "STRINGDAT.DAT"); 
READ(STRING_FILE,STRING_VAR); 

CLOSE(STRING.FILE); 
end SHOW_SEQ; 


The item input-output operations provided by SEQUENTIAL_MIXED_IO 
are basically the same as those provided for the other mixed-type pack¬ 
ages. See Figure 2-1 (in Section 2.6) and Examples 2-2 (in Section 2.6.2) 
and 2-5 (in Section 2.6.4) for examples of using the item input-output 
operations. 


2.6.2 Using Direct Files 

For creating and working with direct files of uniform-type elements, VAX 
Ada provides the generic package DIRECT_IO; for creating and working 
with direct files of mixed-type elements, VAX Ada provides the nongeneric 
package DIRECT_MIXED_IO. 

When you create a file with either of these packages, the file will have 
the default file attributes listed in Table 2-7 or Table 2-8. These packages 
can be used only with files having the FDL attributes ORGANIZATION 
SEQUENTIAL and RECORD FORMAT FIXED. If you attempt to use 
DIRECT—IO or DIRECT_MIXED_IO with a file that has different 
ORGANIZATION and RECORD FORMAT attributes, the exception 
USE-ERROR will be raised. 
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Note that when creating files with the package DIRECT—IO, you must 
specify a maximum record size with the FORM parameter if you instan¬ 
tiate the package with an unconstrained element type. When creating 
files with the package DIRECT_MIXED_IO, you must always specify a 
maximum record size with the FORM parameter. The maximum record 
size determines the maximum size of an element in the file. In the case 
of DIRECT_MIXED_IO, it also determines the size of the file buffer for 
performing item input-output. If you write a value to a direct file element 
that is smaller than the size specified, the corresponding external file 
record is padded with zeros. 

Direct files can be read-shared only. 

Table 2-7: DIRECT—IO: Default File Attributes 


File Attribute 

Default Value 

FILE 

ORGANIZATION 

SEQUENTIAL 

RECORD 

CARRIAGE-CONTROL 

CARRIAGE-RETURN 

FORMAT 

FIXED 

SIZE 

(ELEMENT—TYPE'MACHINE—SIZE + 7)/8 
if ELEMENT—TYPE is constrained; otherwise 
a value must be specified (no default if 
ELEMENT—TYPE is unconstrained) 

ACCESS 

GET 

YES 

PUT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN-FILE; 

NO if MODE is OUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

CONNECT 

UPDATE—IF 

YES 
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Table 2-8: DIRECT_MIXED_IO: Default File Attributes 


File Attribute 

Default Value 

FILE 

ORGANIZATION 

SEQUENTIAL 

RECORD 

CARRIAGE-CONTROL 

CARRIAGE-RETURN 

FORMAT 

FIXED 

SIZE 

None; this attribute must be specified in the 
FORM parameter 

ACCESS 

GET 

YES 

PUT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN-FILE; 

NO if MODE is OUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

CONNECT 

UPDATE—IF 

YES 


Example 2-2 shows the reading and writing of items into a direct file, 
using the package DIRECT—MIXED—IO (for an example of using the pack¬ 
age DIRECT—IO, see Figure 2-2 in Section 2.6). Note from Example 2-2 
that reads and writes do not have to be to consecutive elements; how¬ 
ever, if you read from an empty element, the value returned will be 
unpredictable. 
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Example 2-2: Using Package DIRECT—MIXED—IO 


with DIRECT_MIXED_IO; use DIRECT_MIXED_IO; 
procedure SHOW_DIRECT_MIXED is 

OLD_STRING : STRING(1..5) := "FOUR 

NEW.STRING : STRING(1..5) := "FIVE "; 

OLD.INT : INTEGER := 1; 

NEW.INT : INTEGER := 4; 


MY.FILE : FILE_TYPE; 


-- Instantiate GET and PUT procedures 


procedure GET.INT is new GET.ITEM(INTEGER); 
procedure GET.STR is new GET.ITEM(STRING); 
procedure PUT.INT is new PUT.ITEM(INTEGER); 
procedure PUT.STR is new PUT.ITEM(STRING); 

begin 

-- Create the file; sequential organization is the default, 
-- but is specified for completeness; a record size 
-- must be specified (there is no default) 


CREATE(FILE => MY.FILE, 

MODE => INOUT.FILE, 

NAME => "MY_FILE.DAT", 

FORM => "FILE;" 

"ORGANIZATION SEQUENTIAL;" 
"RECORD;" 

"SIZE 120;" 


& 

& 

& 

); 


-- Alternately put a string in the buffer and write it 
-- to the file as a single-element record 


PUT_STR(MY_FILE,OLD_STRING); 

WRITE(FILE => MY_FILE, 

TO => 1); -- string will be written to element 1 

PUT_STR(MY_FILE,OLD_STRING); 

WRITE(FILE => MY_FILE); -- string will be written to element 2 


(Continued on next page) 
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Example 2-2 (Cont.): Using Package DIRECT_MIXED_IO 


PUT_STR(MY_FILE,OLD_STRING); 

WRITE(FILE => MY_FILE, 

TO => 5); — string will be written to element 5 

SET_INDEX(MY_FILE, 7); -- reposition file pointer to element 7 

PUT_INT(MY_FILE,0LD_INT); 

WRITE(FILE => MY_FILE); -- integer will be written to element 7 

-- Reset for reading 

RESET(MY.FILE); 

-- Read values out of file 

READ(MY_FILE); -- put the record from element 1 

-- into the buffer 
GET_STR(MY_FILE,NEW_STRING); 

READ(FILE => MY_FILE, -- put the record from element 7 

FROM => 7) ; -- into the buffer 

end SHOW_DIRECT_MIXED ; 


2.6.3 Using Relative Files 

For creating and working with relative files of uniform-type elements, 
VAX Ada provides the generic package RELATIVE_IO; for creating and 
working with relative files of mixed-type elements, VAX Ada provides the 
nongeneric package RELATIVE_MIXED_IO. 

When you create a file with either of these packages, the file will have 
the default file attributes listed in Table 2-9 or Table 2-10. You can 
use RELATIVE—IO and RELATIVE_MIXED_IO only with files having 
the attribute ORGANIZATION RELATIVE. If you attempt to use these 
packages with a file with any other ORGANIZATION attribute, the 
exception USE_ERROR will be raised. 

Note that when creating files with the package RELATIVE_IO, you 
must specify a maximum record size with the FORM parameter if you 
instantiate the package with an unconstrained element type. When 
creating files with the package RELATIVE_MIXED__IO, you must always 
specify a maximum record size with the FORM parameter. The maximum 
record size determines the maximum size of an element in the file. In 
the case of RELATIVE_MIXED_IO, it also determines the size of the file 
buffer for performing item input-output. 

Relative files can be read and write-shared. 
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Table 2-9: RELATIVE-IO: Default File Attributes 


File Attribute 

Default Value 

FILE 

ORGANIZATION 

RELATIVE 

RECORD 

CARRIAGE-CONTROL 

CARRIAGE-RETURN 

FORMAT 

FIXED if ELEMENT_TYPE is constrained; 
VARIABLE if not 

SIZE 

(ELEMENT—TYPE'MACHINE—SIZE + 7)/8 
if ELEMENT—TYPE is constrained; if not, a 
value must be specified (there is no default 
if ELEMENT—TYPE is unconstrained) 

ACCESS 

DELETE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

GET 

YES 

PUT 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

UPDATE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN-FILE; 

NO if MODE is OUT-FILE or INOUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 


I 
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Table 2-10: RELATIVE—MIXED_IO: Default File Attributes 


File Attribute 

Default Value 

FILE 

ORGANIZATION 

RELATIVE 

RECORD 

CARRIAGE—CONTROL 

CARRIAGE—RETURN 

FORMAT 

VARIABLE 

SIZE 

None; a value must be specified in the 
FORM parameter 

ACCESS 

DELETE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if mode is IN-FILE 

GET 

YES 

PUT 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

UPDATE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN—FILE; 

NO if MODE is OUT-FILE or INOUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE; 

NO if MODE is INOUT-FILE or IN-FILE 


Example 2-3 shows the reading and writing of records to cells in a relative 
file using the package RELATIVE_IO. Reads and writes to relative files do 
not have to be to consecutively numbered; however, if you attempt to read 
at a position for which there is no element, the exception EXISTENCE- 
ERROR will be raised. 
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Example 2-3: Using Package RELATIVE-.IO 


with RELATIVE.10; 
procedure SHOW.RELATIVE.IO is 

type SMALL.RECORD is 

record 

NUM: INTEGER := 0; 

LET: CHARACTER := 'A'; 

end record; 

-- Instantiate and make visible a RELATIVE.IO package 
-- that operates on elements of type SMALL.RECORD 


package REC.IO is new RELATIVE.IO(SMALL.RECORD); 
use REC.IO; 


-- Declare the objects to be used 


RELATIVE.FILE 

POS 

REC 

RECX 

RECY 

I 


FILE.TYPE; 

POSITIVE.COUNT; 

SMALL.RECORD; 

SMALL .RECORD := (NUM => 1, LET => 'X’); 
SMALL .RECORD := (NUM => 2, LET => •Y'); 
INTEGER; 


begin 

-- Create the file 


CREATE(RELATIVE.FILE,OUT.FILE,"RELATIVE.FILE.DAT"); 

— Write records, incrementing the NUM value, to file 
-- cells in positions 1 through 10 

for I in 1..10 loop 

WRITE(RELATIVE.FILE,REC); 

REC.NUM := REC.NUM + 1; 

end loop; 

-- Prepare file for reading 

RESET(RELATIVE.FILE,IN.FILE); 


(Continued on next page) 
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Example 2-3 (Cont.): Using Package RELATIVE—IO 


— Read contents of records in cells at positions 2 and 3 

POS := INDEX(RELATIVE_FILE); 

READ(RELATIVE_FILE,RECX,2); 

POS := INDEX(RELATIVE_FILE); 

. READ(RELATIVE_FILE,RECY); 

-- Prepare file for writing 

RESET(RELATIVE_FILE,0UT_FILE); 

-- Write to records in cells at positions 12 and 16 

WRITE(RELATIVE_FILE,REC,12); 

REC.NUM := REC.NUM + 1; 

WRITE(RELATIVE_FILE,REC,16); 

end SHOW_RELATIVE_IO; 


The item input-output operations provided by RELATIVE_MIXED_IO are 
basically the same as those provided for the other mixed-type packages. 
See Figure 2-1 (in Section 2.6) and Examples 2-2 (in Section 2.6.2) 
and 2-5 (in Section 2.6.4) for examples of using the item input-output 
operations. 


2.6.4 Using Indexed Files 

For creating and working with indexed files of uniform-type elements, 
VAX Ada provides the generic package INDEXED__IO; for creating and 
working with indexed files of mixed-type elements, VAX Ada provides the 
nongeneric package INDEXED_MIXED_IO. 

When you create a file with either of these packages, the file will have 
the defaults listed in Table 2-11 or 2-12. You can use these packages 
only with files having the attribute ORGANIZATION INDEXED. If you 
attempt to use INDEXED_IO or INDEXED_MIXED_IO with a file that 
has a different ORGANIZATION attribute, the exception USE_ERROR 
will be raised. 

Note that when creating indexed files, you must use the FORM parameter 
to specify any information about the keys (no default key values are 
provided by the CREATE procedures). Also note that there is no default 
bucket size; if you do not specify a bucket size with the FORM parameter. 
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VAX RMS calculates the bucket size based on the maximum record size 
(the default is 0). 

Indexed files can be read and write-shared. 

Table 2-11: INDEXED—IO: Default File Attributes 


File Attribute 

Default Value 

FILE 

ORGANIZATION 

INDEXED 

RECORD 

CARRIAGE-CONTROL 

CARRIAGE-RETURN 

FORMAT 

FIXED if ELEMENT-TYPE is constrained; 
VARIABLE if not 

SIZE 

(ELEMENT—TYPE'MACHINE—SIZE + 7)/8 
if ELEMENT—TYPE is constrained; 0 if not 
(there is no maximum record size; note, 
however, that SIZE is also limited by bucket 
size; see the VAX/VMS Record Management 
Services Reference Manual) 

ACCESS 

DELETE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

GET 

YES 

PUT 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

UPDATE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN-FILE; 

NO if MODE is OUT-FILE or INOUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 
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Table 2-12: INDEXED—MIXED—IO: Default File Attributes 


File Attribute 

Default Value 

FILE 

ORGANIZATION 

INDEXED 

RECORD 

CARRIAGE-CONTROL 

CARRIAGE-RETURN 

FORMAT 

VARIABLE 

SIZE 

0 (the record size is unlimited; note, how¬ 
ever, that the record size is limited by 
the bucket size; see the VAX/VMS Record 
Management Services Reference Manual) 

ACCESS 

DELETE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

GET 

YES 

PUT 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

UPDATE 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN-FILE; 

NO if MODE is OUT-FILE or INOUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE or INOUT- 
FILE; 

NO if MODE is IN-FILE 


You can access indexed files with both sequential and keyed access 
methods. Sequential reading retrieves consecutive components, which are 
sorted according to the specified key field. Keyed access permits random 
component selection according to the value of a particular key field. Once 
you select a key, a sequential read (using the READ procedure) retrieves 
components with ascending key field values. 

Example 2-4 shows the use of package INDEXED_IO to create and 
maintain a database of information about classic books. The example 
makes use of a package of types and operations used in the database, and 
demonstrates the use of the READ_BY__KEY procedure. Example 2-5 
shows the use of package INDEXED_MIXED_IO, and demonstrates how 
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to create a mixed-type indexed file, and then shows how to read and write 
from the file using the primary key. 

Example 2-4: Using Package INDEXED—IO 


package CLASSIC_EXAMPLE is 

-- Subtypes for describing the length and indices of 

— the TITLE string 

subtype TITLE_LAST_RANGE is NATURAL 
range 0..100; 

subtype TITLE_INDEX_RANGE is NATURAL 
range 1 .. TITLE_LAST_RANGE' last ; 

type GENRE.TYPE is (DETECTIVE, ROMANCE, SCI.FI, OTHER); 

— Abstract description of a record in the CLASSICS database 

type CLASSIC(TITLE.LENGTH : TITLE_LAST_RANGE := 0) is 

record 

TITLE : STRING(TITLE_INDEX_RANGE 

range 1..TITLE_LENGTH); 

GENRE : GENRE.TYPE; 

POPULARITY : FLOAT range -10.0 .. 10.0; 

end record; 

subtype LARGEST.CLASSIC is 

CLASSIC(TITLE_INDEX_RANGE' last); 

-- Operations supported on the CLASSICS database 

procedure CREATE_NEW_DATA_BASE; 

procedure ENTER_CLASSIC(NEW_CLASSIC : CLASSIC); 

function RETRIEVE_CLASSIC(TITLE:STRING) return CLASSIC; 

NO_SUCH_CLASSIC : exception; 


(Continued on next page) 
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Example 2-4 (Cont.): Using Package INDEXED_IO 


private 

— Physical description of a record in the CLASSICS data base; 
-- note that the representation comment for TITLE is given only 

— for completeness (TITLE is a dynamic component) 

for CLASSIC use 
record at mod 4; 


TITLE.LENGTH 

at 

0 

range 

0 . 

. 31; 

GENRE 

at 

4 

range 

0 . 

• 31; 

POPULARITY 

at 

8 

range 

0 . 

• 31; 

TITLE 

at 

12 

range 

0 . 

. TITLE_INDEX_RANGE'last*8-l; 


end record; 

end CLASSIC.EXAMPLE; 

with INDEXED_IO; 

package body CLASSIC.EXAMPLE is 

— Instantiate INDEXED_IO with an element type that represents 

— the largest possible CLASSIC 

package CLASSIC.IO is new INDEXED_IO(LARGEST_CLASSIC); 
use CLASSIC_IO; 

— Database file object 
CLASSIC_DATA_BASE : FILE_TYPE; 

-- Predefined name string that gives the external file name 
CLASSIC_DATA_BASE_NAME_STRING : constant 
STRING := "CLASSIC_DATA_BASE.DAT"; 

DATA_BASE_OPEN : BOOLEAN := FALSE; 


(Continued on next page) 
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Example 2-4 (Cont.): Using Package INDEXED—IO 


— Procedure used locally by the ENTER and RETRIEVE operations 
procedure OPEN_DATA_BASE is separate; 

-- Operations used externally for creating and maintaining the 
-- database 

procedure CREATE_NEW_DATA_BASE is separate; 
procedure ENTER_CLASSIC(NEW_CLASSIC : CLASSIC) is separate; 
function RETRIEVE_CLASSIC(TITLE:STRING) 
return CLASSIC is separate; 

end CLASSIC.EXAMPLE; 


-- Separate subprograms and main program to test the database 


-- Procedure to open the database file and set a flag to 
-- indicate that the file is open 

separate (CLASSIC.EXAMPLE) 
procedure OPEN_DATA_BASE is 

begin 

OPEN(FILE => CLASSIC_DATA_BASE, 

MODE => INOUT.FILE, 

NAME => CLASSIC_DATA_BASE_NAME_STRING); 
DATA_BASE_OPEN := TRUE; 

end; 


(Continued on next page) 
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Example 2-4 (Cont.): Using Package INDEXED-IO 


-- Procedure to create the database and give the external 
— file indexed attributes 

separate (CLASSIC_EXAMPLE) 
procedure CREATE_NEW_DATA_BASE is 

— LARGEST_CLASSIC record object used to set the size of 
— the external file records and the key segments 

DUMMY : LARGEST.CLASSIC; 

-- Constant form string for the data base; note that 
-- some default indexed file characteristics are specified 
-- for completeness (see Table 2-11 for the defaults) 


CLASSIC_DATA_BASE_FORM_STRING : constant STRING := 

"FILE;" & 

"ORGANIZATION INDEXED;" & 

"RECORD;" & 

"CARRIAGE_C0NTR0L CARRIAGE_RETURN;" & 

"FORMAT VARIABLE;" & 

"SIZE" & INTEGER'IMAGE(DUMMY 1 SIZE/8) & & 

"KEY 0;" & 

"CHANGES NO;" & 

"DUPLICATES NO;" & 

"PROLOG 3;" & 


"SEGO_LENGTH" & INTEGER'IMAGE(DUMMY.TITLE'SIZE/8) & ";" & 
"SEGO.POSITION" & INTEGER'IMAGE(DUMMY.TITLE'POSITION) & ";" & 
"TYPE STRING;"; 


(Continued on next page) 
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Example 2-4 (Cont.): Using Package INDEXED—IO 


— Create the file using the constant name string from the 
-- CLASSIC_EXAMPLE package body and the constant form string 
-- given above; set the flag that tells whether or not the 
-- file is open 


begin 

CREATE(FILE => CLASSIC_DATA_BASE, 

MODE => INOUT.FILE, 

NAME => CLASSIC_DATA_BASE_NAME_STRING, 
FORM => CLASSIC_DATA_BASE_FORM_STRING); 
DATA_BASE_OPEN := TRUE; 
end CREATE_NEW_DATA_BASE; 


-- Procedure to enter the information about a classic 
-- into the database 

separate(CLASSIC.EXAMPLE) 

procedure ENTER_CLASSIC(NEW_CLASSIC : CLASSIC) is 

-- Pad the key field (TITLE) out to its full length 
— because indexed file (ISAM) keys must have a 
-- constant length 

EXPANDED.CLASSIC : LARGEST_CLASSIC := 

CLASSIC'(TITLEJLENGTH => TITLE_INDEX_RANGE'LAST, 

TITLE => NEW.CLASSIC.TITLE & 

(NEW_CLASSIC.TITLE_LENGTH+1 .. 

TITLE_INDEX_RANGE'LAST=>' '), 
GENRE => NEW_CLASSIC.GENRE, 

POPULARITY => NEW.CLASSIC.POPULARITY); 

begin 

if not DATA_BASE_OPEN 
then OPEN_DATA_BASE; 

end if; 

WRITE(CLASSIC_DATA_BASE, EXPANDED.CLASSIC); 
end ENTER.CLASSIC; 


(Continued on next page) 
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Example 2-4 (Cont.): Using Package INDEXED_IO 


-- Function to retrieve a classic record from the database 


separate (CLASSIC_EXAMPLE) 

function RETRIEVE.CLASSIC(TITLE:STRING) return CLASSIC is 
RETRIEVED.CLASSIC : LARGEST.CLASSIC; 

subtype EXPANDED.TITLE is STRING(TITLE_INDEX_RANGE); 

procedure READ_CLASSIC_BY_KEY is new READ_BY_KEY(EXPANDED.TITLE); 

begin 

if not DATA_BASE_OPEN then 
OPEN_DATA_BASE; 

end if; 

READ_CLASSIC_BY_KEY( 

FILE => CLASSIC_DATA_BASE, 

ITEM => RETRIEVED.CLASSIC, 

KEY => TITLE & (1..EXPANDED.TITLE'LAST - TITLE'LENGTH => ' ')); 


for I in reverse TITLE.INDEX.RANGE loop 

if RETRIEVED.CLASSIC.TITLE(I) /= ' ' then 
return 


CLASSIC'( 


TITLE.LENGTH 

=> 

TITLE 

=> 

GENRE 

=> 

POPULARITY 

=> 


end if; 
end loop; 


I. 

RETRIEVED.CLASSIC.TITLECl..1), 
RETRIEVED.CLASSIC.GENRE, 
RETRIEVED.CLASSIC.POPULARITY); 


exception 

when EXISTENCE.ERROR => 
raise NO.SUCH.CLASSIC; 
end RETRIEVE.CLASSIC; 


(Continued on next page) 


Input-Output Facilities 2-55 






Example 2-4 (Cont ): Using Package INDEXED—IO 


-- Main program to show that the database operations work 


with CLASSIC.EXAMPLE; with TEXT.IO; 
use CLASSIC.EXAMPLE; use TEXT.IO; 
procedure TEST.CLASSIC_DATA.BASE is 


A.FAMOUS.TITLE : constant STRING := "Never Heard of It"; 


A.FAMOUS.CLASSIC 

(TITLE.LENGTH 

TITLE 

GENRE 

POPULARITY 


: constant CLASSIC := 

=> A.FAMOUS.TITLE'LENGTH, 
=> A.FAMOUS.TITLE, 

=> SCI.FI, 

=> ”5.0); 


AN.UNKNOWN.TITLE : constant STRING := "This is not a Title"; 


AN.UNKNOWN.CLASSIC : constant CLASSIC := 
(TITLE.LENGTH => AN.UNKNOWN.TITLE'LENGTH, 

TITLE => AN.UNKNOWN.TITLE, 

GENRE => OTHER, 

POPULARITY => 5.0); 


RETRIEVED.CLASSIC : CLASSIC; 

begin 

PUT.LINE("Create"); 

CREATE.NEW_DATA.BASE; 

PUT.LINE("Enter"); 

ENTER.CLASSIC(A.FAMOUS.CLASSIC); 

ENTER.CLASSIC(AN.UNKNOWN.CLASSIC); 

PUT.LINE("Retrieve"); 

RETRIEVED.CLASSIC := RETRIEVE.CLASSIC(AN.UNKNOWN.TITLE); 
if RETRIEVED.CLASSIC /= AN.UNKNOWN.CLASSIC then 

PUT.LINE("***failed to retrieve the UNKNOWN classic"); 

end if; 

RETRIEVED.CLASSIC := RETRIEVE.CLASSIC(A.FAMOUS.TITLE); 
if RETRIEVED.CLASSIC /= A.FAMOUS.CLASSIC then 

PUT_LINE("***failed to retrieve the FAMOUS classic"); 

end if; 

end TEST.CLASSIC_DATA.BASE; 
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Example 2-5: Using Package INDEXED_MIXED_IO 


with INDEXED_MIXED_IO; use INDEXED_MIXED_IO; 
procedure SHOW_INDEXED_MIXED is 

type INTEGER_ARRAY_TYPE is array (INTEGER range <>) of INTEGER; 
type COLORS is (RED,BLUE,YELLOW); 


-- Declare objects to be used to fill the file with values 


INDEXED_FILE 
INTEGER,ARRAY 
INTI, INT2, INT3, 

INT4, INT5, INT6, INT7 : 
CHARI, CHAR2, 

CHAR3, CHAR4 
C0L1, C0L2 
ARRAY,INDEX 


FILE.TYPE; 

INTEGER_ARRAY_TYPE(1..3); 

INTEGER; 

CHARACTER; 

COLORS; 

INTEGER; 


-- Instantiate generic READ_BY_KEY procedures 


procedure READ_0 is new READ_BY_KEY(INTEGER,0); 
procedure READ_1 is new READ_BY_KEY(CHARACTER,1); 

-- Instantiate generic GET_ITEM and PUT.ITEM procedures 


procedure 

procedure 

procedure 

procedure 


GET.INT is 
GET_FL0AT is 
GET.CHAR is 
GET.ENUM is 


new GET_ITEM(INTEGER); 
new GET.ITEM(FLOAT); 
new GET.ITEM(CHARACTER); 
new GET_ITEM(COLORS); 


procedure PUT.INT is new PUT_ITEM(INTEGER); 
procedure PUT_FL0AT is new PUT.ITEM(FLOAT); 
procedure PUT.CHAR is new PUT.ITEM(CHARACTER); 
procedure PUT_ENUM is new PUT.ITEM(COLORS); 


procedure GET_ARRAY_INT is new 

GET_ARRAY(INTEGER,INTEGER,INT_ARRAY_TYPE); 


(Continued on next page) 
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Example 2-5 (Cont.): Using Package IIMDEXED-MIXED-IO 


begin 

-- Create the file 


CREATE(FILE => INDEXED_FILE, 

MODE => 0UT_FILE, 

NAME => "F.DAT", 

FORM => "FILE;" k 

"ORGANIZATION INDEXED;" k 
"KEY 0;" k 

"INDEX.FILL 4;" k 

"TYPE INT4;" k 

"DUPLICATES YES;" k 

"POSITION 0;" k 

"LENGTH 4;" k 

"KEY 1;" k 

"INDEX.FILL 1;" k 

"TYPE STRING;" k 

"DUPLICATES YES;" k 

"POSITION 4;" k 

"LENGTH 1;" ); 


-- Fill the element buffer with a character, an integer, 
-- and an enumeration value 


INTI := 1; 

CHARI := 'A'; 

C0L1 := YELLOW; 

PUT_INT(INDEXED_FILE,INTI); 
PUT_CHAR(INDEXED_FILE,CHARI); 
PUT_ENUM(INDEXED_FILE,C0L1); 
-- Write the element to the file 


WRITE(INDEXED_FILE); 


(Continued on next page) 


2-58 Input-Output Facilities 


Example 2-5 (Cont.): Using Package IIMDEXED_MIXED_IO 


-- Prepare to read the record from the file 

RESET(INDEXED_FILE,INOUT_FILE) ; 

-- Read the record from the file sorting on 
-- the primary key (integer) 

READ_0(INDEXED_FILE,INTI,0); 
GET_INT(INDEXED_FILE,INT2); 

GET_CHAR(INDEXED_FILE,CHAR2); 

GET_ENUM(INDEXED_FILE,C0L2); 

-- Prepare to add more elements to the file 

RESET(INDEXED_FILE); 

SET_POSITION(INDEXED_FILE,1); 

-- Fill the buffer with an integer, a character, 

-- and three more integers, and write the buffer to 
-- the file 

INT3 := 3; 

CHAR3 := 'B'; 

INT4 := 4; 

INT5 := 5; 

INT6 := 6; 

PUT_INT(INDEXED_FILE,INT3); 

PUT_CHAR(INDEXED_FILE,CHAR3); 

PUT_INT(INDEXED_FILE,INT4); 

PUT_INT(INDEXED_FILE,INT5); 

PUT_INT(INDEXED_FILE,INT6); 

WRITE(INDEXED_FILE) ; 


(Continued on next page) 
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Example 2-5 (Cont.): Using Package IIMDEXED_MIXED_IO 


-- Read the record from the file sorting on 
-- key 1 (string) 

READ.1(INDEXED.FILE,CHAR3.1) ; 

-- Get the items from the buffer; in particular, read 
-- three integers directly into the integer array 

GET.INT(INDEXED.FILE,INT7); 

GET.CHAR(INDEXED.FILE.CHAR4); 

GET.ARRAY.INTCINDEXED.FILE,INTEGER.ARRAY,ARRAY.INDEX); 


CLOSE(INDEXED.FILE); 
end SHOW.INDEXED.MIXED; 


2.6.5 Using Text Files 

For creating and working with text files, VAX Ada provides the nongeneric 
package TEXT_IO. When you create a file with this package, the file will 
have the defaults listed in Table 2-13. 

The package can be used only with files that have the attribute 
ORGANIZATION SEQUENTIAL; for example, you could open and 
read files created with the packages SEQUENTIAL_IO, SEQUENTIAL— 
MIXED—IO, DIRECT—IO, or DIRECT_MIXED_IO. If you attempt to use 
this package with files that have a different ORGANIZATION attribute, 
the exception USE_ERROR will be raised. 

Text files can be read-shared only. 
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Table 2-13: Default File Attributes Provided by Package 
TEXT—IO 


File Attribute 

Default Value 

FILE 

ORGANIZATION 

SEQUENTIAL 

SEQUENTIAL-ONLY 

YES 

RECORD 

CARRIAGE-CONTROL 

PRINT if device is a terminal; CARRIAGE- 
RETURN otherwise 

FORMAT 

VFC if device is a terminal; VARIABLE 
otherwise 

SIZE 

0 (record size is unlimited; note, however, 
that the record size has physical limitations; 
see the VAX/VMS Record Management 
Services Reference Manual) 

ACCESS 

GET 

YES 

PUT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

TRUNCATE 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 

SHARING 

GET 

YES if MODE is IN—FILE; 

NO if MODE is OUT-FILE 

PROHIBIT 

YES if MODE is OUT-FILE; 

NO if MODE is IN-FILE 


From Table 2-13 you can see that VAX Ada text files are implemented as 
VAX RMS sequential files. Each line in a text file corresponds to a single 
RMS record (VAX Ada text files are not stream files). 

Although VAX Ada creates text files with variable-length records by 
default, you can use the FORM parameter (see Section 2.3) to create text 
files with fixed-length records. When a text file with fixed-length records 
is being written, the line length (if nonzero) must be less than or equal 
to the record size. The exception USE_ERROR is raised if you attempt 
to change the line length to a value greater than the record size. This 
exception is also raised when a line being written is longer than the record 
size. When you write a program that creates text files with fixed-length 
records, you should set the line length to the record size. If the line being 
written does not fill the entire (fixed-length) record, spaces are used to pad 
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the rest of the record (and the spaces are then regarded as characters in 
the file). 

Example 2-6 shows the use of TEXT_IO to write text from a terminal to a 
file. 

Example 2-6: Using Package TEXT—IO 


with TEXT.IO; use TEXT.IO; 
procedure COPY is 

MY_COPY : FILE_TYPE; 

INPUT.80 : STRING (1..80); 

CURRENT.PAGE : POSITIVE.COUNT; 

LAST : NATURAL; 

begin 

CREATE(MY_COPY, OUT.FILE, "MY_COPY.TXT"); 

PUT_LINE("Start typing your book."); 

PUT_LINE("Type CTRL/Z to finish."); 

loop 

-- Remember current page, then get at most 
-- 80 characters, then write out the line 
-- to the text file. 

CURRENT.PAGE := PAGE (CURRENT.INPUT); 

GET.LINE (INPUT.80, LAST); 

PUT (MY.COPY, INPUT_80(1..LAST)); 

-- If typist starts a new page then terminate 
-- the page in the file. Do not write an explicit 
-- end-of-page if page change is as a result 
-- of end of file (CTRL/Z). Otherwise, start 
-- a new line. 

if CURRENT.PAGE < PAGE (CURRENT.INPUT) then 
if not END.OF.FILE then 
NEW.PAGE (MY.COPY); 

end if; 
else 

NEW.LINE (MY.COPY); 

end if; 
end loop; 


(Continued on next page) 
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Example 2-6 (Cont.): Using Package TEXT-.IO 


exception 

when END_ERR0R => 

NEW.LINE (3); 

PUT ("Your text is in file MY_COPY.TXT"); 
CLOSE (MY.COPY); 
end COPY; 


When working with text input-output in general, and with terminal input- 
output in particular, you should keep in mind that each VAX Ada 
TEXT—IO operation behaves exactly as it is described in the VAX Ada 
Language Reference Manual. For example, if you run the following program 

with TEXT_IO; use TEXT.IO; 
procedure SH0W_GETS is 

INOUT.LINE: STRING(1..10) := "tenletters"; 

LAST.CHAR: NATURAL; 

begin 

PUT_LINE("Do a GET.LINE"); 

GET_LINE(IN0UT_LINE,LAST_CHAR); 

PUT_LINE(INOUT_LINE); 

PUT_LINE("Do another GET.LINE"); 

GET_LINE(IN0UT_LINE,LAST_CHAR); 

PUT(IN0UT_LINE); 
end; 

and type CTRL/Z as the only input to the GET_LINE operation, the im¬ 
mediate result is that the VAX/VMS exit prompt appears on your screen, 
and then the string "tenletters" is printed. The result occurs because 
GET—LINE is defined as a procedure that replaces the characters of its 
string argument with input characters until it encounters a line terminator. 
Because CTRL/Z in this case represents a line terminator followed by a 
page terminator followed by a file terminator (see Section 2.6.5.2), 
GET—LINE immediately encounters a line terminator. Then, according 
to the definition of GET—LINE, SKIP—LINE is called, and the subsequent 
page terminator is skipped. The initial string is output because it has 
not been changed by GET—LINE. Because the file terminator remains as 
input for the next GET—LINE operation, when that operation is executed, 
the exception END—ERROR is raised. Note that if the first GET—LINE 
had been a GET, the exception END—ERROR would have been raised 
immediately. 
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You should also be aware that when you do a SKIP_LINE operation in 
VAX Ada (or any operation that, in effect, does a SKIP_LINE, such as a 
GET_LINE; see Chapter 14 of the VAX Ada Language Reference Manual), 
the skipping of the page terminator (if any) is delayed. A subsequent 
operation may require that the skipped page terminator be retrieved, and 
the result is a request for more input from the file. This delaying process 
enables a GET_LINE operation from a terminal device to be (partially) 
satisfied immediately after a carriage return and then for execution of the 
program to continue. 


2.6.5.1 Line Terminators, Page Terminators, and File Terminators 

The Ada language defines "logical" text files and text file operations in 
terms of line terminators, page terminators, and file terminators (see 
Chapter 14 of the VAX Ada Language Reference Manual). That is, a text 
file is logically structured such that the end of a line is marked by a line 
terminator (LT), the end of a page is marked by a line terminator followed 
by a page terminator (LT PT), and the end of a file is marked by a line 
terminator followed by a page terminator followed by a file terminator 
(LT PT FT). Figure 2-3 shows a simple, three-page text file. 

Figure 2-3: An Ada Text File, Showing Line, Page, and File 
Terminators 


Column number 



ZK-4041-85 
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The VAX Ada interpretation of these terminators is as follows: 

• A line terminator (LT) is designated by the end of a VAX RMS record, 
except when the next record in the file logically represents a line 
terminator followed by a page terminator (LT PT; see the next item). 

In an empty file, a line terminator is designated by the end of the file. 

• A line terminator followed by a page terminator (LT PT) is designated 
by one of the following: 

— An entire record consisting of a single form-feed control character 
(for text files with variable-length records). 

— An entire record with a form-feed control character as the first byte 
of the record (for text files with fixed-length records). 

— An empty record with VAX RMS PRN information that indicates 

a form-feed control character (for variable-length with fixed-length 
control records and files created with the CARRIAGE-CONTROL 
PRINT attributes). 

— The end of the file, whenever the last record of the file does not 
itself represent a page terminator (that is, when the last record does 
not represent a line terminator followed by a page terminator; 

LT PT). 

• A file terminator (FT) is designated by the end of the file. An empty 
file thus represents a line terminator followed by a page terminator 
followed by a file terminator (LT PT FT). If the file is not empty and 
the last record of the file does not represent a line terminator followed 
by a page terminator (LT PT) (if, for example, the file consists of a 
single line ending in only a line terminator), then the end of the file 
represents a page terminator followed by a file terminator (PT FT). 
When the last record of the file represents a line terminator followed 
by a page terminator (LT PT), the end of the file is a file terminator 
(FT). 

For example, an external file created by the following three operations 
contains exactly one empty record: 

CREATE (MY_FILE); 

NEW_LINE(MY_FILE); 

CLOSE (MY_FILE); 

Because the NEW-LINE procedure uses the default spacing of 1, and be¬ 
cause no new pages are created, the NEW—LINE in this example produces 
one line terminator (LT). In this case, a line terminator is represented by 
a single, empty RMS record in the corresponding external file. (See the 
VAX Ada Language Reference Manual for a complete description of the 
NEW—LINE procedure.) 
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By replacing the NEW_LINE operation with a NEW_PAGE operation, 
you would produce a file with one record consisting of a single form-feed 
control character. (MY_FILE has variable-length records because it is 
created using the default attributes provided by TEXT_IO.) By eliminating 
the NEW—LINE operation altogether, you would produce an empty file. 
All three cases mentioned produce the same logical file consisting of a line 
terminator followed by a page terminator followed by a file terminator 

(Li PT FT) 


2.6.5.2 Text Input-Output Buffering 

VAX Ada TEXT_IO operations are implemented with RMS input-output 
operations. Because RMS operations always involve complete records, 
the transfer of characters between a physical input-output device and a 
VAX Ada text file is complete only when a line terminator is detected. 
Therefore, in most cases, as characters are read or written to a VAX Ada 
text file, they are stored in an internal line buffer until a complete record 
can be transferred through RMS. 

Thus, when you are performing either terminal or nonterminal input , 
information from the external file is transferred and processed a line (an 
RMS record) at a time. Hence, terminal input is not processed until the 
line is terminated by a carriage return (or other line terminator). 

It is possible to provide more information in a line than the current input 
operation needs. In that case, the remaining characters are kept in a buffer 
to be processed by subsequent input operations. Each time an operation 
requires more input from the external file, a new read operation from that 
file is initiated. 

When you are performing either terminal or nonterminal output, the output 
is also buffered until a line terminator is encountered. In other words, 
the output is buffered until a NEW__LINE or a NEW_PAGE (or any other 
operation that in effect performs a NEW_LINE or a NEW—PAGE, such as 
PUT_LINE) is executed. 

Partial buffering is done when you are performing terminal output and you 
have specified the attributes FDL CARRIAGE—CONTROL CARRIAGE- 
RETURN or CARRIAGE-CONTROL PRINT in a CREATE or OPEN 
FORM parameter (see Section 2.3). (PRINT is the default CARRIAGE- 
CONTROL attribute provided by the package TEXT—IO for external files 
that are terminals; see Table 2-13). 

Partial buffering means that PUT operations to the terminal output file are 
buffered until 

• Input is attempted for any other file that is associated with the same 
terminal device (for example, your program executes a PUT, or a series 
of PUTS, followed by a GET). 


2-66 


Input-Output Facilities 


• Execution of one or more PUT operations causes 1000 or more charac¬ 
ters to be written to the buffer. 

When one of these actions occurs, the contents of the file buffer is output 
to your terminal, whether or not the record represented by the buffer is 
complete. For example, the following program buffers the four characters 
produced by the PUT operations, and then, when the GET is executed, 
prints the letters "abed" on the screen as a single line and prompts for 
input. 

with TEXT.IO; use TEXT.IO; 
procedure PRINTCHAR is 
C: CHARACTER; 
begin 

PUT('a'); 

PUT('b'); 

PUT('c'); 

PUT('d'); 

GET(C); 

PUT(C); 
end; 


The contents of any text file buffers (partial or full) are also written to 
your terminal (flushed) whenever your program image is exited (such as 
when an unhandled exception propagates out of a main program). In this 
situation, all unclosed files are also closed by an exit handler. 


2.6.5.3 TEXT—IO Carriage Control 

The FDL CARRIAGE-CONTROL attribute specifies the carriage control 
format for a file. In addition, it allows you to control line buffering for 
files being written to terminal devices. 

As described in Section 2.3, you can specify the CARRIAGE—CONTROL 
attribute with a FORM parameter as follows 


TEXT.10.CREATE 


(FILE => file.object.name, 

MODE => OUT.FILE, 

NAME => externaL.file.name, 

FORM => "RECORD; CARRIAGE.CONTROL value;"); 


TEXT.10.OPEN 


(FILE => file.object.name, 

MODE => 0UT.FILE, 

NAME => externaL.file.name, 

FORM => "RECORD; CARRIAGE.C0NTR0L value;"); 


Note that the CARRIAGE—CONTROL attribute is a creation-time attribute 
(see Section 2.3.2), and whatever is specified when a text file is created 
cannot be changed on subsequent openings of the same file. 
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The possible CARRIAGE-CONTROL values are 


CARRIAGE-RETURN 

PRINT 


NONE 


FORTRAN 


The default if the device is not a terminal; generally 
provides the desired behavior for most terminal and 
nonterminal applications. 

The default if the device is a terminal and the file 
mode is OUT—FILE; results in the use of a variable- 
length with fixed length control (VFC) record format. 
The control portion of each record contains carriage 
control information that indicates line and page 
boundaries. 

Useful in applications that need to randomly move the 
cursor and update the terminal screen. Output to files 
specified with this option is buffered until an operation 
that requires a line terminator is executed. Calls to 
PUT—LINE or NEW—LINE can be used to control 
when the actual VAX RMS line termination operation 
occurs. 

Useful for applications that want to use FORTRAN 
carriage control characters. 


Table 2-14 summarizes the meaning of the FDL CARRIAGE—CONTROL 
values when they applied to VAX Ada text files, (for both terminal and 
nonterminal input-output). 


Table 2-14: VAX Ada Carriage Control Options 


Option Kind of 

Input-Output 

CARRIAGE—RETURN Terminal input 

Nonterminal input 


Terminal output 


Carriage Control 


Each record corresponds 
to a single line. A one- 
byte record containing a 
form feed designates a 
page. 

A VFC record format 
with a two-byte control 
portion is used regard¬ 
less of what is specified 
in the form string. The 
control portion of the 
record specifies the 
carriage-control informa¬ 
tion (line feed, carriage 
return, null, or page). 
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Table 2-14: (Cont.) VAX Ada Carriage Control Options 


Option 


PRINT 


NONE 


Kind of 
Input-Output 

Nonterminal output 


Terminal input 


Nonterminal input 


Terminal output 
Nonterminal output 


Nonterminal input 
Terminal input 


Carriage Control 


The record attributes 
for the file imply that 
each record is preceded 
by a line feed and 
followed by a carriage 
return when the file is 
displayed or printed. 

A one-byte record 
containing a form feed 
designates a page. 

Each record corresponds 
to a single line. A one- 
byte record containing a 
form feed designates a 
page. 

Control information 
indicates that a page is 
interpreted as a page 
terminator. Otherwise, 
a record is assumed to 
correspond to a line. 

A VFC record format 
with a two-byte control 
portion is used regard¬ 
less of what is specified 
in the form string. The 
control portion of the 
record specifies the 
carriage-control informa¬ 
tion (line feed, carriage 
return, page). 

Each record corresponds 
to a single line. A one- 
byte record containing a 
form feed designates a 
page. 
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Table 2-14: (Cont.) VAX Ada Carriage Control Options 


Option 

Kind of 

Input-Output 

Carriage Control 


Terminal output 

An RMS record is 


Nonterminal output 

written whenever an 
operation is executed 
that requires a line 
terminator. However, 
no carriage control 
information is written 
for lines, and the record 
attributes for the file do 
not imply that records 
are preceded by a line 
feed or followed by a 
carriage return. A one- 
byte record containing a 
form feed designates a 
page. 

FORTRAN 

Terminal input 

The first byte of each 


Nonterminal input 

record (containing 
carriage control infor¬ 
mation) is considered 
to be data. Each record 
corresponds to a single 
line. A one-byte record 
containing a form feed 
designates a page. 


Terminal output 

No carriage control 


Nonterminal output 

information is supplied 
by VAX Ada. The first 
byte PUT by the user in 
each line is interpreted 
as a FORTRAN carriage 
control character (see 
Table 2-15). 
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Table 2-15: FORTRAN Carriage-Control Characters 


Character 

Meaning 

V 

/ / 

Overprinting: starts output at the beginning of the current line. 
Single spacing: starts output at the beginning of the next line. 

'O' 

Double spacing: skips a line before staring output. 

T 

Paging: starts output at the top of a new page. 


Prompting: starts output at the beginning of the next line and 
suppresses carriage return at the end of the line. 

' '(0) 

Prompting with overprinting: suppresses line feed at the 
beginning of the line and carriage return at the end of the line; 
note that this is the ASCII null character. 


2.6.5.4 Predefined Instantiations of TEXT—IO Packages 

To make your use of the generic TEXT_IO operations more efficient, 
VAX Ada provides a set of predefined library packages that instantiate 
the integer and floating-point operations for the predefined integer and 
floating-point types: 


Package Name 


Instantiation 


INTEGER_TEXT_IO 

SHORT_INTEGER_TEXT_IO 

SHORT_SHORT_INTEGER_TEXT_IO 

FLOAT_TEXT_IO 
LONG_FLOAT_TEXT_IO 
LONG—LON G—FLO AT_TEXT_IO 


INTEGER_IO(INTEGER) 

INTEGER_IO(SHORT_INTEGER) 

INTEGER_IO(SHORT_SHORT_ 

INTEGER) 

FLOAT_IO(FLOAT) 

FLOAT_IO(LONG_FLOAT) 

FLOAT_IO(LONG_LONG_FLOAT) 
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Thus, instead of writing out the instantiation for INTEGER—IO in each 
program unit that does text input-output of integers, you can make the 
predefined package available to the applicable units (or to your whole 
program). For example: 


with INTEGER_TEXT_IO; use INTEGER_TEXT_IO; 
procedure WRITEOUT_INTEGERS is 
A,B: INTEGER; 
begin 

A := 10; 

PUT(A); 

B := A**2; 

PUT(B); 


end WRITEOUT.INTEGERS; 

Note that the predefined package is produced by compiling the equivalent 
of the following instantiation 


with TEXT.IO; 

package INTEGER_TEXT_I0 is new TEXT.IO.INTEGER_I0(INTEGER); 

If you want to use other TEXT—IO operations, such as string operations 
or INTEGER_TEXT_IO operations that involve files other than standard 
files (files you declare in your program), you must also make the package 
TEXT—IO available to your program: 


with TEXT.IO; use TEXT.IO; 
with INTEGER_TEXT_IO; use INTEGER_TEXT_IO; 
procedure WRITE_STRINGS_AND_INTS is 
X: INTEGER; 

F: FILE.TYPE; 


begin 

PUT("The value 
X := -24; 

PUT(X); 
NEW.LINE; 
CREATE(F); 

PUT(F,X); 


of X is "); -- 


TEXT_I0.PUT 

INTEGER_TEXT_IO.PUT 
TEXT_I0.NEW_LINE 
TEXT.IO.CREATE 
INTEGER_TEXT_IO.PUT 


end WRITE_STRINGS_AND_INTS; 

Similar comments apply to the other predefined instantiations of 
TEXT—IO. 
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2.7 Input-Output and Tasking 


In VAX Ada, operations on the same file are synchronized so that they 
take place sequentially, rather than concurrently. In other words, oper¬ 
ations on the same file are "indivisible". Thus, if one task is performing 
an operation on a file and another task attempts to perform an operation 
on the same file, VAX Ada causes the second task to wait until the earlier 
operation is finished. Any number of tasks may be waiting for a file to be 
released by a task that is performing an operation on that file. This syn¬ 
chronized access to file objects allows multiple tasks to perform concurrent 
input-output operations on the same file object without corrupting the file. 

To illustrate, if one task executes PUT(F, "Bryant") and another task 
concurrently executes PUT(F, "Steve"), where F is a file object, the external 
file associated with F receives either "Steve Bryant" or "Bryant Steve". 

VAX Ada will not produce "St Breveyant". 

In general, any operation in the predefined input-output packages that 
results in an RMS record operation is process asynchronous and task 
synchronous. That is, the predefined input-output operations suspend the 
task (make it wait) until the operation is completed, while other tasks in 
the process are allowed to continue. 

The exception is for operations to process permanent files (SYS$INPUT, 
SYS$OUTPUT, SYS$COMMAND, and SYS$ERROR). These external files 
do not allow operations to be process asynchronous; any input-output 
operations will suspend your process and all tasks in your program. 

This is of particular importance when you are using tasks to perform 
input-output on the standard input and output text files, which are 
implicitly defined to be SYS$INPUT and SYS$OUTPUT, respectively. 

You can control this behavior by defining files other than SYSSINPUT 
and SYS$OUTPUT and equating them to the predefined logical names 
ADA$INPUT and ADA$OUTPUT. Then, any calls to operations in the 
package TEXT_IO from a task will open those files (that is, will assume 
that they are the standard files). For example, to have a task perform 
input-output to and from your terminal without suspending your process, 
you could use the DCL ASSIGN command to associate ADA$INPUT and 
ADA$OUTPUT with TT:, which is not a process permanent file. 

Note that the synchronization described in this section applies to internal 
files (VAX Ada file objects). Synchronization of input-output to an external 
file shared among multiple internal files is performed by RMS through 
record locking. 
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2.8 Error Reporting 


The VAX Ada input-output packages raise errors that are defined in the 
packages IO-EXCEPTIONS and AUX_IO_EXCEPTIONS. See the VAX 
Ada Language Reference Manual for descriptions of these errors and the 
operations that raise them. See Chapter 6 of this manual for information 
on exception handling. 
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Chapter 3 

Object Representation and Storage 


This chapter describes how objects are represented and stored. Section 3.1 
describes the representations chosen by the VAX Ada compiler for objects 
of any VAX Ada type; Section 3.2 explains how you can change the 
default representations by using representation clauses and the pragma 
PACK; and Section 3.3 shows the use of attributes to determine the 
amount of storage associated with a type or allocated for an object. 
Section 3.4 explains how you can share object storage with non-Ada 
programs. 

You should be familiar with the material in Chapters 3 and 13 of the VAX 
Ada Language Reference Manual before trying to use the material in this 
chapter. 


3.1 Type and Object Representations 

The representation of any Ada object is determined by its type. That 
is, associated with each type are a size and a particular layout of bits 
that are used by the compiler to allocate storage for an object of that 
type when the object is declared. In most cases, this representation is 
determined at compile time; however, in the case of types that involve 
dynamic components (records with variants, arrays with variable bounds, 
and records or arrays with dynamic components), the representation is 
determined partially at compile time and partially at run time. 

The following sections describe the VAX Ada types and the representa¬ 
tions chosen by the VAX Ada compiler for objects of any type. 
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3.1.1 Integer Types 

VAX Ada provides three integer types. Objects of type SHORT_SHORT_ 
INTEGER are stored in a byte (8 bits); objects of type SHORT-INTEGER, 
in a word (16 bits); and objects of type INTEGER, in a longword (32 bits). 

Values for objects of all three integer types are represented as signed, 
two's complement (binary) numbers. You can achieve an unsigned repre¬ 
sentation by declaring a derived integer type with a length representation 
clause (see Section 3.2.2). Table 3-1 gives the range of integer values 
allowed for each Ada predefined integer type. 


Table 3-1: Range of Values for Predefined Integer Types 


Type 

Storage Size 
(bits) 

Range of Values 

SHORT_SHORT_INTEGER 

8 

-(2**7)..(2**7)-1 



-128..127 

SHORT_INTEGER 

16 

-(2**15)..(2**15)-1 

-32,768.32,767 

INTEGER 

32 

-(2**31)..(2**31)-1 



-2,147,483,648.-2,147,483,647 


3.1.2 Enumeration Types 

As defined by the Ada language, each literal in an enumeration type 
corresponds to an integer code. Thus, the amount of storage allocated for 
an object of an enumeration type is determined by the amount of storage 
required to represent the range of integer codes represented by the type. 
For example: 

type ANSWER is (YES, NO, UNDECIDED); 

Here, a byte (8 bits) is allocated to store values of type ANSWER because 
a byte is all that is needed to represent the three integer codes (0..2). 

For this same reason, a byte (8 bits) is allocated to store values of the 
predefined type BOOLEAN (in package STANDARD). To force 1-bit 
BOOLEAN representations, you can use length and representation clauses 
and pragma PACK. See Section 3.2.1 of this manual and Chapter 13 of 
the VAX Ada Language Reference Manual . 
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The default range of codes for enumeration literals is 0..N-1 (where N is 
any positive integer up to 2**16), and the integer representation of the 
codes is unsigned. By declaring an enumeration type with an enumeration 
representation clause, you can choose a particular range of codes for that 
type. You can also achieve a signed representation (see Section 3.2.3). 


3.1.3 Floating-Point Types 

The storage size for an object of a floating-point type depends on the 
representation of that type. When you use one of the VAX Ada predefined 
floating-point types or when you define your own floating-point type, the 
compiler chooses one of the four floating-point data representations 
provided by the VAX architecture (F_floating, D_floating, G_floating, or 
H_floating). Sections 3.1.3.2 through 3.1.3.5 illustrate and explain these 
representations. 

For the predefined floating-point types , the choice of representation is 
straightforward; see Table 3-2. 

Table 3-2: VAX Type Representations and Storage Sizes 
for VAX Ada Floating-Point Types 


Ada Type 

VAX Representation 

Storage Size 
(bits) 

Defined in STANDARD: 



FLOAT 

F_floating 

32 

LONG_FLOAT 

D_floating or G_floating 1 

64 

LONG_LONG_FLOAT 

H_floating 

128 

Defined in SYSTEM: 



F-FLOAT 

F_floating 

32 

D-FLOAT 

D_floating 

64 

G-FLOAT 

G_floating 

64 

H-FLOAT 

H_floating 

128 


1 By default, or in the presence of pragma LONG_FLOAT(G_FLOAT), LONG_FLOAT has a 
G_floating representation; it has a D_floating representation in the presence of pragma LONG— 
FLOAT(D_FLOAT). You can also use the ACS commands CREATE LIBRARY, CREATE SUBLIBRARY, 
and SET PRAGMA to control the representation of type LONG_FLOAT. This pragma is discussed in 
more detail in Section 3.1.3.1 of this manual and in Chapter 3 of the VAX Ada Language Reference 
Manual. The ACS commands are described in Developing Ada Programs on VAX/VMS. 


For all VAX Ada floating-point types, the Ada language rules about 
model numbers and safe numbers apply (see Chapter 3 of the VAX Ada 
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Language Reference Manual). That is, a set of model numbers and a set of 
safe numbers are defined for each VAX representation.' The set of model 
numbers is determined such that the following relationships are true: 

• The number of decimal digits of precision (D) times 3.32 (the approxi¬ 
mate number of bits needed to represent one digit) is less than or equal 
to the number of mantissa bits (B) in the representation. 

• The range of exponents is from -4*B to 4*B. 

The model numbers for each VAX floating-point type (and thereby for 
each VAX Ada predefined floating-point type) are given in Table 3-3. 
Note that the ranges are approximate; the exact ranges are listed in 
Appendix F of the VAX Ada Language Reference Manual, or you can find 
them with the attributes T'SMALL and T'LARGE. Also note that only 
positive ranges are given; all floating-point numbers are, in fact, signed, 
and an equivalent negative range (as well as zero) is provided for each 
type. 

Table 3-3: Model Numbers Defined for Each Floating-Point Type 


VAX Ada Types and 
Representations 

Digits ( D ) 

Mantissa 
Bits (B) 

Exponent 
Range (4*B) 

Approximate Range 

F_floating 

F_FLOAT 

FLOAT 

6 

21 

-84 . 

. 84 

2.5E-26 . 

. 1.9E+25 

D_floating 

D_FLOAT 
LONG_FLOAT 

9 

31 

-124 . 

. 124 

2.3E-38 . 

. 2.1E+37 

G—floating 

G-FLOAT 

LONG_FLOAT 

15 

51 

-204 . 

. 204 

1.9E-62 . 

. 2.5E+61 

H_floating 

H-FLOAT 

LONG_LONG_FLOAT 

33 

111 

-444 . 

. 444 

1.1E-134 . 

. 4.5E+133 


The set of safe numbers (which, by definition, includes the model num¬ 
bers) is determined such that the following relationships are true: 

• The number of mantissa bits is the same as that defined for the model 
numbers of the type. 

• The range of exponents is from -E to +E, where E is at least equal 
to 4*B, and is determined from the number of exponent bits in the 
representation. 
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Thus, for each VAX floating-point type, the safe numbers are the full range 
of numbers that can be represented by that type; the model numbers are a 
special subset over which certain kinds of accuracy can be guaranteed (see 
Chapter 4 of the VAX Ada Language Reference Manual). 

The safe numbers for each VAX floating-point type (and thereby for 
each VAX Ada floating-point type) are given in Table 3-4. Note that the 
positive ranges are approximate; the exact ranges are listed in Appendix 
F of the VAX Ada Language Reference Manual, or you can find them with 
the attributes T'SAFE_SMALL and T'SAFE_LARGE. Again, only positive 
ranges are given here; each range also includes an equivalent set of 
negative values as well as zero. 

Table 3-4: Safe Numbers Defined for Each Floating-Point Type 


VAX Ada Types and 
Representations 

Digits (D) 

Mantissa 
Bits (B) 

Exponent 

Range (4*B) 

Approximate Range 

F__floating 

F_FLOAT 

FLOAT 

6 

21 

-127 .. 

127 

2.9E-39 

.. 1.7E+38 

D_floating 

D_FLOAT 

LONG_FLOAT 

9 

31 

-127 .. 

127 

2.9E-39 

,. 1.7E+38 

G_floating 

G-FLOAT 

LONG_FLOAT 

15 

51 

-1023 .. 

1023 

5.5E-309 . 

. 8.9E+307 

H_floating 

H-FLOAT 

LONG_LONG_FLOAT 

33 

111 

-16383 .. 

16383 

8.4E-4933 . 

. 5.9E+4931 


For user-defined floating-point types, the choice of representation depends 
on the precision (digits) and range specified. When you declare your own 
floating-point types, the compiler first finds a set of model numbers that 
provides the number of digits specified. 
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If the G_floating representation of type LONG_FLOAT is in effect for the 
compilation (see Table 3-2 and Section 3.1.3.1), the following representa¬ 
tions are used (assuming the specified range can also be accommodated): 


Digits Specified 

G_Floating 

Representations 

1 .. 6 

F_floating 

7 .. 15 

G_floating 

16 .. 33 

H_floating 

If pragma LONG_FLOAT(D_FLOAT) has been specified for the compi¬ 
lation (see Section 3.1.3.1), the following representations are used (again, 
assuming the specified range can also be accommodated): 

Digits Specified 

D_floating 

Representations 

1 .. 6 

F_floating 

7 .. 9 

D_floating 

10 .. 33 

H_floating 


After determining a set of model numbers that satisfies the precision, the 
compiler checks to see if the same set of numbers satisfies the specified 
range. If so, the representation with those model numbers is chosen; if 
not, the compiler finds another set of model numbers that satisfies both 
the precision and the range. The compiler evaluates the available repre¬ 
sentations, in the order F_floating, D_floating, H_floating or 
F_floating, G_floating, H_floating (depending on the current representa¬ 
tion being used for type LONG_FLOAT), until it finds a satisfactory set of 
numbers. 

For example, if you had the following declaration 

pragma LONG_FLOAT(D_FLOAT); 
package FLOAT.TYPES is 

type MAYBE.D is digits 9 range -0.1E-50 .. 0.1E+50; 
end FLOAT.TYPES; 

the compiler would choose the VAX H_floating representation for 
MAYBE_D. Although a D_floating representation satisfies the precision, it 
does not satisfy the range. 


3-6 


Object Representation and Storage 


In all cases, the choice of representation for a floating-point type is deter¬ 
mined by the model number limits. However, once the representation is 
chosen, the full accuracy of the underlying VAX floating-point type is used 
in any calculations involving numbers of that type. Thus, if you declared 
the type 

type SURE_TO_BE_D is digits 9 range -100.0 .. 100.0; 

in package FLOAT-TYPES, the full 16 decimal digits of accuracy pro¬ 
vided by the VAX D_floating hardware representation would be used in 
calculations involving objects of type SURE—TO_BE_D. 


3.1.3.1 Pragma LONG-FLOAT 

The VAX Ada predefined pragma LONG—FLOAT has the effect of a 
library switch that controls whether the G_floating or D_floating rep¬ 
resentations are used to represent type LONG—FLOAT. Its use implies 
a recompilation of the predefined STANDARD environment for a given 
library. See the VAX Ada Language Reference Manual for the specific 
rules governing the use of this pragma; see Developing Ada Programs on 
VAX/VMS for a discussion of the implications of recompiling package 
STANDARD. 

For example, the compilation of the following unit would cause all sub¬ 
sequent compilations in the same library to use the set of representations 
that include D_floating, as appropriate (see Section 3.1.3): 

pragma L0NG_FL0AT(D_FL0AT); 
package USE__D_FL0AT is 

type MY_D_FL0AT is digits 9 range -100.0 .. 100.0; 

— D_floating representation will be used 

type MY_H_FL0AT is digits 11 range -100.0 .. 100.0; 

-- H_floating representation will be used 
D_0BJECT: L0NG_FL0AT; 

-- D_floating representation will be used 
end USE_D_FL0AT; 

To return to G_floating representations, you could compile another unit 
(in the same library) that contains pragma LONG— 

FLOAT(G_FLOAT), you could use the ACS command SET PRAGMA, 
or you could recreate your library with the ACS DELETE and CREATE 
commands. If package USE—D_FLOAT were in a sublibrary, you could 
also control the representation of MY_D_FLOAT and D_OBJECT with 
the ACS CREATE SUBLIBRARY command. See Developing Ada Programs 
on VAX/VMS for information on the ACS commands. 


Object Representation and Storage 3-7 


3.1.3.2 VAX F_floating Representation 

An F_floating-point number (single precision) is represented in memory 
by four contiguous bytes. The bits are numbered from the right, 0 through 
31, as shown in Figure 3-1. 

Figure 3-1: F_floating Representation 
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An F_floating-point value is specified by its address, that is, the address of 
the byte containing bit 0 (address A in Figure 3-1). The form of the value 
is signed magnitude as follows: 

• Bit 15 is the sign bit. 

• Bits 14 through 7 are an excess 128 binary exponent. 

• Bits 6 through 0 and 31 through 16 are a normalized 24-bit fraction, 
with the redundant most significant fraction bit not represented. 
Within the fraction, bits of increasing significance go from 16 through 
31 and from 0 through 6. 

The 8-bit exponent field encodes the values 0 through 255: 

• An exponent value of 0, with a sign bit of 0, indicates that the floating¬ 
point number has a value of 0. 

• Exponent values of 1 through 255 indicate binary exponents of -127 
through +127. 

If you are doing unchecked type conversions to or from floating-point 
types (see Chapter 13 of the VAX Ada Language Reference Manual), you 
should note that an exponent value of 0, with a sign bit of 1, is considered 
a reserved operand. Floating-point instructions that process a reserved 
operand cause a reserved operand fault. 

In VAX Ada, the VAX F_floating representation is used to represent the 
set of model numbers shown in Table 3-3 and the set of safe numbers 
shown in Table 3-4. On VAX machines, the value of an F_floating- 
point number is in the approximate range of 0.29*(10**-38) through 
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1.7*(10**38). The precision of an F_floating-point value is approximately 
one part in 2**23, or 7 decimal digits. 


3.1.3.3 VAX D_floating Representation 

A D_floating-point number (double precision) is represented in memory 
by 8 contiguous bytes. The bits are numbered from the right, 0 through 
63, as shown in Figure 3-2. 

Figure 3-2: D_floating Representation 
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A D_floating-point value is specified by its address, that is, the address of 
the byte containing bit 0 (address A in Figure 3-2). The form of a 
D_floating-point value is identical to that of an F_floating-point value, 
except for an additional 32 low-significance fraction bits. Within the 
fraction, bits of increasing significance are numbered 48 through 63, 32 
through 47, 16 through 31, and 0 through 6. 

In VAX Ada, the VAX D_floating representation is used to represent the 
set of model numbers shown in Table 3-3 and the set of safe numbers 
shown in Table 3-4. On VAX machines, the exponent conventions and 
approximate range of values are the same for D_floating-point values as 
for F_floating-point values. However, the precision of a D_floating-point 
value is approximately one part in 2**55, or 16 decimal digits. 
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VAX G—floating Representation 

A G_floating-point number (double precision) is represented in memory 
by 8 contiguous bytes. The bits are numbered from the right, 0 through 
63, as shown in Figure 3-3. 

Figure 3-3: G_floating Representation 
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A G_floating-point value is specified by its address, that is, the address 
of the byte containing bit 0 (address A in Figure 3-3). The form of a 
G_floating-point value is signed magnitude as follows: 

• Bit 15 is the sign bit. 

• Bits 14 through 4 are an excess 1024 binary exponent. 

• Bits 3 through 0 and 63 through 16 represent a normalized 53-bit frac¬ 
tion, with the redundant most significant fraction bit not represented. 
Within the fraction, bits of increasing signficance go from 48 through 
63, 32 through 47, 16 through 31, and 0 through 3. 

The 11-bit exponent field encodes the values 0 through 2047: 

• An exponent value of 0, with a sign bit of 0, indicates that the 
G_floating-point number has a value of 0. 

• Exponent values of 1 through 1047 indicate binary exponents of -1023 
through +1023. 

If you are doing unchecked type conversions to or from floating-point 
types (see Chapter 13 of the VAX Ada Language Reference Manual), you 
should note that an exponent value of 0, with a sign bit of 1, is considered 
a reserved operand. Floating-point instructions that process a reserved 
operand cause a reserved operand fault. 
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In VAX Ada, the VAX G_floating representation is used to represent the 
set of model numbers shown in Table 3-3 and the set of safe numbers 
shown in Table 3-4. On VAX machines, the value of a G_floating- 
point number is in the approximate range of 0.56*(10**-308) through 
0.90(10**308). The precision of a G_floating-point value is approximately 
one part in 2**52, or 15 decimal digits. 


3.1.3.5 VAX H_floating Representation 

An H_floating-point (quadruple precision) value is represented in memory 
by 16 contiguous bytes. The bits are numbered from the right, 0 through 
127, as shown in Figure 3-4. 

Figure 3-4: H—floating Representation 
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An H_floating-point value is specified by its address, that is, the address 
of the byte containing bit 0 (address A in Figure 3-4). The form of an 
H_floating-point value is signed magnitude as follows: 

• Bit 15 is the sign bit. 

• Bits 14 through 0 are an excess 16,384 binary exponent. 
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• Bits 127 through 16 are a normalized 113-bit fraction, with the redun¬ 
dant most significant fraction bit not represented. Within the fraction, 
bits of increasing significance go from 112 through 127, 96 through 
111, 80 through 95, 64 through 79, 48 through 63, 32 through 47, and 
16 through 31. 

The 15-bit exponent field encodes the values 0 through 32,767: 

• An exponent value of 0, with a sign bit of 0, indicates that the 
H_floating-point number has a value of 0. 

• Exponent values of 1 through 32,767 indicate binary exponents of 
-16,383 through +16,383. 

Should you be doing unchecked type conversions to or from floating-point 
types (see Chapter 13 of the VAX Ada Language Reference Manual ), you 
should note that an exponent value of 0, with a sign bit of 1, is considered 
a reserved operand. Floating-point instructions that process a reserved 
operand cause a reserved operand fault. 

In VAX Ada, the VAX H_floating representation is used to represent the 
set of model numbers shown in Table 3-3 and the set of safe numbers 
shown in Table 3-4. On VAX machines, the value of an H_floating- 
point number is in the approximate range of 0.84*(10**-4932) through 
0.59*(10**4932). The precision of an H_floating-point value is approxi¬ 
mately one part in 2**112, or 33 decimal digits. 


3.1.4 Fixed-Point Types 

The storage size for an object of any fixed-point type is a longword (32 
bits). Values for objects of a fixed-point type are represented as signed, 
two's complement (binary) numbers with an implicit binary scale factor. 

As with floating-point types, fixed-point types and their operations are 
defined in terms of model numbers and safe numbers. See Chapter 3 of 
the VAX Ada Language Reference Manual for more information. 
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3.1.5 Array Types 


The storage size for an object of an array type is the number of array 
components multiplied by the size of one component. (By definition, all 
array components must have the same type and thus have the same size.) 

For example: 

type COLORS is (RED, ORANGE, YELLOW, GREEN, BLUE, VIOLET); 
type SPECTRUM is array(1..10) of COLORS; 

WHITE.LIGHT: SPECTRUM; 

Because values of type COLORS are stored in a byte (see Section 3.1.2), 
and SPECTRUM has 10 components of type COLOR, 10 bytes are allo¬ 
cated for WHITE_LIGHT. 

Arrays of more than one dimension are treated similarly. Thus, in the 
example 

subtype INT is INTEGER range 1..10; 

type TW0_DIM_ARRAY (INT range <>, INT range <>) of CHARACTER; 
CHAR_ARRAY: TWO.DIM ARRAY(1..5,5..10); 

CHAR_ARRAY is stored in 30 bytes (30 8-bit components). Note that 

multidimensional arrays are stored in row-major order. 

The components of all VAX Ada arrays are byte-aligned by default. To 
force bit alignment and/or to minimize gaps, you must use pragma PACK 
with the array type declaration (see Section 3.2.1). 


3.1.6 Record Types 

The storage size for an object of a record type is a function of the sizes 
and alignments of the record components. The representation of a record 
object value varies, depending on whether or not discriminants, variants, 
or record representation clauses are involved. 

In VAX Ada, record types are laid out such that all components affected by 
representation clauses in the record declaration appear first. The remain¬ 
ing components are then laid out in the order in which they appear in 
the record declaration; discriminants unaffected by representation clauses 
precede the remaining components. Thus, in the following example 

type SIMPLE.ARRAY is array (INTEGER range <>) of BOOLEAN; 
type SIMPLE.LAY0UT (I,J: INTEGER) is 
record 

A: INTEGER; 

B: SIMPLE.ARRAY(I..J); 

end record; 


Object Representation and Storage 3-13 




the components are laid out with the discriminants I and J first, and then 
A and B. 

In another example 

type SHOW_LAYOUT (DISCRIMINANT: BOOLEAN) is 
record 

A: INTEGER; 

case DISCRIMINANT is 

when TRUE => B: CHARACTER; 
when FALSE => C: INTEGER; 
end case; 
end record; 

the components are laid out such that DISCRIMINANT appears first, 
then A. Then, because they are not affected by representation clauses, 
the variants are laid out starting on the first byte boundary after A (the 
compiler "overlays" variants when laying out record types). 

If, on the other hand, SHOW-LAYOUT were declared with a represen¬ 
tation clause that specifically placed a component of one of the variants 
elsewhere, that variant would be laid out first. Thus, if SHOW—LAYOUT 
were modified as follows 

type SHOW.LAYOUT (DISCRIMINANT: BOOLEAN) is 
record 

A: INTEGER; 

case DISCRIMINANT is 

when TRUE => B: CHARACTER; 
when FALSE => C: INTEGER; 
end case; 
end record; 

for SHOW.LAYOUT use 

record 

B at 0*8 range 0..7; 
end record; 

the compiler would lay out B first, then DISCRIMINANT, then A, then 
C. (Do not confuse the layout of a type with the layout of an object: 
an object of constrained subtype SHOW—LAYOUT(TRUE) would have 
the components B, DISCRIMINANT, A, in that order; an object of con¬ 
strained subtype SHOW—LAYOUT(FALSE) would have the components 
DISCRIMINANT, A, C.) 

For any record type, dynamic components—components that are dynam¬ 
ically sized, such as records with variants, arrays with variable bounds, 
and records or arrays with dynamic components—are dynamically allo¬ 
cated and cause any succeeding components unaffected by representation 
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clauses to also be dynamically allocated (whether they are themselves 
dynamic components or not). Thus, in the following example 

type COMPONENT_ARRAY is array (INTEGER range <>) of INTEGER; 
type ANOTHER.ORDER (I,J: INTEGER) is 

record 

A: COMPONENT_ARRAY(I..J); 

B: INTEGER; 

end record; 

A and B are both dynamically allocated: A because it is a dynamic 
component (an array with variable bounds), and B because its location 
depends on the size of A. 

The laying out of a record type allows the compiler to determine the 
size of the type, where the size of the type is also the size of the largest 
possible object of that type. The size is related not to the sum of the sizes 
of the record's components, but to where the last component has been 
laid out, including any allowances that have been made for alignments. In 
other words, the size of a record type is computed as the position of the 
last component that physically appears in the layout plus the size of the 
last component (rounded up to a byte boundary if necessary). (Rounding 
depends on whether or not the component is packable; see Section 3.2.1.) 

Consider the following example: 

type BIT.ARRAY is 

array (INTEGER range <>, INTEGER range <>) of BOOLEAN; 
pragma PACK (BIT.ARRAY); 
subtype N is INTEGER range 1..25; 
type OFFICE_SECTION_LAYOUT (LENGTH : N := 1; 

WIDTH : N := 1) is 

record 

OCCUPIED : BIT_ARRAY(1..LENGTH, 1..WIDTH); 

end record; 

FL00R1 : OFFICE_SECTION_LAYOUT; 

The discriminants LENGTH and WIDTH of subtype N, which could have 
a maximum value of 25, each have a default value of 1. The component 
OCCUPIED is an array of 1-bit components whose bounds depend on the 
values of LENGTH and WIDTH. When an unconstrained object, such as 
FLOOR1, is declared, it must be allocated enough storage to accommodate 
a value in which LENGTH and WIDTH could have any value in the range 
1..25. For example, it could be assigned the following aggregate: 

FL00R1 := (20, 25 (1..20 => (1..25 => FALSE))); 

Thus, the storage size allocated for an object like FLOOR 1 must be the 
maximum size that FLOOR1 could be (which is also the size of the type). 
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You can calculate the size as follows. The maximum value for LENGTH 
and WIDTH is 25, and the largest possible OCCUPIED component is a 
25-by-25 array (625 1-bit components). Because LENGTH and WIDTH 
are of an integer subtype, one longword (32 bits) is allocated for each, 
and 625 bits are allocated for the component OCCUPIED. The type is not 
packable (see Section 3.2.1), so the estimated storage is rounded up to a 
byte boundary. Therefore, a total of 88 bytes is allocated for FLOOR1. 

The exact calculation of the size of a record can be nontrivial. For ex¬ 
ample, the size of the following record type can only be calculated by 
determining each possible record object and then choosing the largest 
result (which occurs when D is 5 or 6): 

subtype INT is INTEGER range 1..10; 
type TWO_DIM_ARRAY is 

array (INT range <>, INT range <>) of CHARACTER; 
type REC (D: INT := 1) is 

record 

A: TW0_DIM_ARRAY(1..D,D..10); 

end record; 

RECJDBJECT: REC; 

If you were to calculate by hand the storage needed, you would find that 
if D were 5 (or 6), component A would need storage for 30 components. 
Because objects of type CHARACTER are stored in 8 bits, component 
A would need 240 bits. The total size of the type (and the maximum 
size of REC—OBJECT) would be the storage required for D (32 bits) plus 
the storage required for A (240 bits): a total of 272 bits. This is, in fact, 
the value of REC_OBJECT'SIZE that you get if you examine the size for 
changing values of D. If you simply ask for REC_OBJECT'SIZE (or REC_ 
OBJECT'MACHINE_SIZE, as described in Section 3.3), the compiler uses 
simplifying assumptions to calculate an answer in a reasonable amount 
of time (the answer is, in fact, based on a value of 10 for D, or 112). 
Similar simplifying assumptions are used to calculate REC'SIZE. You 
should be aware that such assumptions are being made when using the 
size attributes with record types and objects whose sizes are not easily 
calculated. 

See Section 3.3 of this manual and Chapter 13 of the VAX Ada Language 
Reference Manual for more information on the size attributes. 
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3.1.7 Access Types 


Because the value of an object of an access type is a VAX virtual address, 
the storage size for an object of an access type is a longword (32 bits). The 
objects designated by values of an access type are sized and represented 
according to their specified types. 

Each access type is associated with a collection, which is storage to be 
used for the objects designated by the type when allocators of that type 
are evaluated. If a nonzero value is specified in a length representation 
clause for the access type (see Chapter 13 of the VAX Ada Language 
Reference Manual), that value determines the number of bytes (rounded 
up to an integral number of 512-byte pages) to be allocated for the 
collection associated with the type. The collection is not extended if it is 
exhausted. If a zero value (or no length representation clause) is specified, 
the effective size of the collection is all of virtual memory; no initial 
allocation is made, and the collection is extended as needed. 

For example, in the following procedure, a 512-byte (1-page) collection 
is initially allocated for the access type NUM_PTR. One allocator is 
evaluated for FIRST_NUM, and 64 allocators are to be evaluated in 
the loop. Each evaluation causes 8 bytes of storage to be allocated; the 
designated object in each case is of type NUM—RECORD, and requires 
a longword (32 bits, or 4 bytes) for the integer component NUM, and 
a longword (32 bits, or 4 bytes) for the access type component (NEXT_ 
NUM). Thus, when I reaches 63, a total of 64 allocators have been 
evaluated, and the collection limit has been reached. When I reaches 
64, the collection limit is exceeded and not extended, and the exception 
STORAGE-ERROR is raised. 

-- procedure to construct a linked-list of integers 

procedure COLLECTION is 
type NUM_RECORD; 

type NUM_PTR is access NUM.RECORD; 
for NUM_PTR'STORAGE_SIZE use 512; 
type NUM_RECORD is 

record 

NUM: INTEGER; 

NEXT_NUM: NUM.PTR; 

end record; 

FIRST_NUM,ASSIGN_NUM: NUM.PTR; 

I: INTEGER; 
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begin 

FIRST.NUM := new NUM_RECORD'(O.null); 

ASSIGN.NUM := FIRST.NUM; 

for I in 1..64 loop 

ASSIGN_NUM.NEXT_NUM := new NUM_RECORD'(I,null); 
ASSIGN.NUM := ASSIGN.NUM.NEXT.NUM; 

end loop; 
end; 


3.1.8 Task Types 

The storage size for an object of a task type is a longword (32 bits); the 
value of an object of a task type is represented as a VAX virtual address. 
When you declare an object of a task type, the value of the object is the 
address of the task control block created for the task. See Chapter 7 for 
information on the allocation of task control blocks and task execution 
stacks. 


3.1.9 Address Types 

The storage size for an object of the VAX Ada address type (type 
ADDRESS, declared in package SYSTEM) is a longword (32 bits); the 
value of an object of an address type is represented as a VAX virtual 
address. 


3.2 Changing Type Representations 

By providing type representation clauses and the language-defined pragma 
PACK, VAX Ada allows you to override the default representations 
supplied by the VAX Ada compiler for some user-defined types. Type 
representation clauses also allow you to control the representation of any 
new or derived types that you declare. 

Sections 3.2.1 and 3.2.2 show how to use pragma PACK and length 
representation clauses to conserve space; Sections 3.2.3 and 3.2.4 show 
how to use enumeration and record representation clauses to affect the 
representation of objects of enumeration and record types. 
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3.2.1 Pragma PACK 


Pragma PACK is provided by the language to allow you to minimize gaps 
between the components of composite types (record and array types). 
When used in a VAX Ada record or array declaration, pragma PACK 
has an effect only if the record or array components are packable. (A 
component is packable if its type allows it to be aligned on an arbitrary bit 
boundary.) Table 3-5 lists the type categories provided in VAX Ada and 
shows whether or not components of each type are packable. 


Table 3-5: 

Packable Types 


Type Category 

Considered 

Packable 
as a Type 

Affected by PACK if a 

Composite Type Component 

Integer 

Yes 

Only if a derived type 

Enumeration 1 

Yes 

Only if a derived type 

Fixed-point 

No 

No 

Floating-point 

No 

No 

Address 

No 

No 

Access 

No 

No 

Task 

No 

No 

Record 

Yes 2 

Only if packable 

Array 

Yes 3 

Only if packable 


1 The predefined enumeration type CHARACTER (in package STANDARD) is implemented as though 
lor CHARACTER'SIZE use 8; 

occurred in STANDARD. Thus, even in the presence of pragma PACK, composite type components of 
type CHARACTER (or derived from type CHARACTER) are not packed into 7 bits. 

2 

If the record type has a compile-time constant size of <= 32 bits, and if all its components are 
packable. 

3 If the array type is itself a packed array of packable arrays, or if it is an array of 1-bit components 
(gained by a representation clause or by packing an array of BOOLEAN components). Components 
of the predefined array type STRING are not packable because type STRING does not have 1-bit or 
packable array components. 


Thus, if you use pragma PACK to pack an array of BOOLEAN com¬ 
ponents, any gaps between the components will be minimized because 
enumeration type components are packable. However, pragma PACK 
would have no effect on an array of floating-point components. 


Object Representation and Storage 3-19 




In the following example, pragma PACK is used to minimize gaps in an 
array of integers that have been given a 3-bit, unsigned representation: 

type UNSIGNED_INTEGER is new INTEGER range 0..7; 
for UNSIGNED.INTEGER'SIZE use 3; 
type UNSIGNED_INTEGER.ARRAY is 

array (INTEGER range <>) of UNSIGNED.INTEGER; 
pragma PACK (UNSIGNED_INTEGER_ARRAY); 

If UNSIGNED-INTEGER_ARRAY were not packed, the space-saving 

benefit of using the length representation clause would be lost, and all of 
the components would be aligned on byte boundaries, causing an 8-bit 
instead of the desired 3-bit component representation. 

When using the PACK pragma, you must be careful to pack at the proper 
level: the pragma packs the components with respect to each other; it 
does not pack the components themselves. In the following example, the 
size of record UNPACKED—COMPONENTS is significantly larger than 
the size of the record PACKED—COMPONENTS, even though both are 
declared with pragma PACK: 

type UNSIGNED.INTEGER is new INTEGER range 0..7; 
for UNSIGNED.INTEGER'SIZE use 3; 

type PACKED.ARRAY is array (1..10) of BOOLEAN; 
pragma PACK (PACKED.ARRAY); 

type UNPACKED.ARRAY is array (1..10) of BOOLEAN; 

type UNPACKED.COMPONENTS is 

record 

A.B: UNSIGNED.INTEGER; 

C: UNPACKED.ARRAY; 

end record; 

pragma PACK (UNPACKED.COMPONENTS); 

type PACKED.COMPONENTS is 

record 

D,E: UNSIGNED.INTEGER; 

F: PACKED.ARRAY; 

end record; 

pragma PACK (PACKED.COMPONENTS); 

BIG.RECORD: UNPACKED.COMPONENTS; — size is 88 bits 

COMPACT.RECORD: PACKED.COMPONENTS; — size is 16 bits 
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The PACK pragma never has an effect on a component that begins a 
record variant. Such components are always allocated on the next byte 
boundary. To force a component that begins a record variant to a bound¬ 
ary other than a byte boundary, you must use a record representation 
clause (see Sections 3.1.6 and 3.2.4 of this manual and Chapter 13 of the 
VAX Ada Language Reference Manual). 


3.2.2 Length Representation Clauses 

Length representation clauses allow you to explicitly control the amount 
of storage associated with a type (and allocated for an object of the type). 
In particular, they are useful for declaring unsigned integers. For example: 

type UNSIGNED_INTEGER is new INTEGER range 0..2**16-1; 
for UNSIGNED_INTEGER'SIZE use 16; 

This declaration causes objects of type UNSIGNED_INTEGER to be 
stored as words, rather than as longwords. 

You could also use a length clause to conserve space if you are working 
with only a narrow range of integer values: 

type UNSIGNED_SMALL_INTEGER is new INTEGER range 0..7; 
for UNSIGNED_SMALL_INTEGER'SIZE use 3; 

The VAX Ada Language Reference Manual gives complete information on 
the use of length clauses. 


3.2.3 Enumeration Representation Clauses 

If you use an enumeration representation clause to specify the integer 
codes for the literals of an enumeration type, the storage size will be the 
amount of storage required to represent the full range of codes specified, 
regardless of the number of enumeration literals. 

For example: 

type ANSWER is (YES, NO, UNDECIDED); 

for ANSWER use (YES => 0, NO => 8, UNDECIDED => 65535); 
MY_UNSIGNED_ANSWER: ANSWER; 

Here, the storage allocated for MY_ANSWER is a word. Even though 

only three integer codes must be represented, a word (16 bits) is needed 
to store values in the range 0..65535. 
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Integer codes are, by default, unsigned; however, if any of the integer 
codes specified by the representation clause are negative, the integer 
representation for the type will be signed. If you were to redeclare type 
ANSWER as follows 

type ANSWER is (NO, YES, UNDECIDED); 

for ANSWER use (NO => -8, YES=> 0, UNDECIDED => 65535); 
MY_SIGNED_ANSWER: ANSWER; 

the integer codes would be signed, and would require one more bit of 
storage than their unsigned counterparts. The storage allocated would be 
a longword. 


3.2.4 Record Representation Clauses 


Record representation clauses allow you to force a record type to have 
a particular representation. Thus, they are useful anytime you need to 
lay out an area of memory in a particular way. For example, you can 
use record representation clauses for laying out a series of objects in a 
particular order. Or, you can use record representation clauses for laying 
out record types that are used to declare objects that may be passed to 
other language routines (including VAX/VMS system routines and VAX 
Run-Time Library routines). 

In declaring record types with variants, you can use record representation 
clauses to conserve space. For example: 

package ALIGN.VAR is 

WORD: constant : = 2; 


type SMALL_INT is new INTEGER range 0..7; 
for SMALL_INT'SIZE use 3; 


type VARIANT.RECORD (VAR: 

record 

A: SMALL.INT; 
case VAR is 

when TRUE => X: 

Y: 

when FALSE => Z: 

end case; 
end record; 


BOOLEAN) is 


CHARACTER 

SMALL.INT 

SMALL.INT 
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for VARIANT.RECORD use 

record 


A at 0*W0RD range 

VAR at 0*W0RD range 

X at 0*W0RD range 

Y at 0*W0RD range 

Z at 0*W0RD range 

end record; 


0. .2; 

3. .3; 

4.. 11; 

12.. 14 

4. .6; 


end ALIGN.VAR; 

The representation clause on type VARIANT-RECORD causes the variant, 
VAR, to be aligned on a bit boundary; when an object is declared and a 
case choice is made, the appropriate component is stored starting on bit 
4 of the word of the storage allocated for the record object. (Without the 
representation clause, the variants would be aligned on byte boundaries.) 

Note that if you declare a record type with fixed-size components which 
follow (or are interspersed with) varying-size components, you will 
generate slower, less efficient code than if you declare a record type where 
all the fixed-size components precede the varying-size components. For 
example: 


package SL0W.LAY0UT is 


type VARYING.ARRAY is array (INTEGER range <>) of BOOLEAN; 

type SLOW.RECORD (I,J: INTEGER) is 
record 

A: INTEGER; 

B: VARYING.ARRAY(I..J); 

C: INTEGER; 

D: VARYING.ARRAY(I..I); 

end record; 


SL0W.0BJECT: SLOW.RECORD(1,10); 
end SLOW.LAYOUT; 


Here, the layout for type SLOW—RECORD can be set up by the compiler 
only to the point of SLOW—RECORD.B; the rest of the layout and the 
allocation of storage for SLOW—OBJECT must be done at run-time. 
Furthermore, each time you access SLOW—OBJECT.B, the size of SLOW— 
OBJECT.A has to be calculated, thus decreasing the efficiency of any code 
that uses SLOW-OBJECT. 
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If the logical layout of a record type such as SLOW_RECORD is im¬ 
portant, you can improve the efficiency of your code by declaring the 
type with a representation clause that forces the fixed-size components to 
known locations. For example: 

package N0T_S0_SL0W_LAY0UT is 

LONGWORD: constant := 4; 

type VARYING.ARRAY is array (INTEGER range <>) of BOOLEAN; 
pragma PACK (VARYING.ARRAY); 

type FASTER.RECORD(I,J: INTEGER) is 
record 

A: INTEGER; 

B: VARYING.ARRAY(I..J); 

C: INTEGER; 

D: VARYING.ARRAY(I..I); 

end record; 

for FASTER.RECORD use 

record 

I at 0*L0NGW0RD range 0..31; 

J at 1*L0NGW0RD range 0..31; 

A at 2*L0NGW0RD range 0..31; 

C at 3*L0NGW0RD range 0..31; 
end record; 

FASTER.OBJECT: FASTER.RECORD(1,10); 
end NOT.SO.SLOW.LAYOUT; 

FASTER_OBJECT is laid out so that the components fall in the following 
order: I, J, A, C, B, D. The type representation clause forces the allocation 
of the components FASTER_OBJECT.B and FASTER_OBJECT.D to the 
end of the record. 


3.2.5 Alignment Clauses 

When you use a record representation clause to define the layout of a par¬ 
ticular record type, you have the option of specifying an alignment clause 
to determine the alignment of all record objects (including record ob¬ 
jects that are components) of that type. The VAX Ada Language Reference 
Manual gives the syntax and rules for using alignment clauses. 
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In VAX Ada, records can be aligned on any byte address that is a multiple 
of a power of 2, up to 512. That is, in the following fragment, the value 
of ALIGN—AT could be any integer in the series 1, 2, 4, 8, . . . , 512. A 
value of 1 would indicate byte alignment, a value of 2 would indicate 
word alignment, and a value of 512 would indicate page alignment. 

type SMALLNUM is new INTEGER range 0..7; 
for SMALLNUM'SIZE use 3; 

ALIGN_AT: constant := 2; 

type ALIGNED_REC0RD is 
record 

Al: BOOLEAN; 

A2: SMALLNUM; 

end record; 

for ALIGNED.RECORD use 
record at mod ALIGN_AT; 

Al at 0*1 range 0 .. 0; 

A2 at 0*1 range 1 .. 3; 
end record; 

type SHOW.ALIGNMENT is 

record 

SI,S2,S3: ALIGNED_RECORD; 

end record; 

In this example, the components of the record SHOW_ALIGNMENT 

are aligned on 2-byte (word) boundaries, and the record SHOW_ 
ALIGNMENT itself is aligned so that its component alignment can be 

observed. If, on the other hand, the value of ALIGN_AT were 16, then 

the components of the record SHOW_ALIGNMENT would be aligned on 
16-byte boundaries. 

If you were to declare an array of components of type ALIGNED— 
RECORD, and apply pragma PACK to the array (which would be le¬ 
gal because the components of ALIGNED—RECORD are packable, and 
the record could have a compile-time size of less than 32 bits), the pragma 
would have no effect because the alignment clause overrides the pragma. 

VAX Ada places some restrictions on the possible alignments, depending 
on how objects of an aligned type are allocated (see Chapter 13 of the 
VAX Ada Language Reference Manual for a list of the restrictions). For 
example, a record object declared in a subprogram will be stack allocated, 
and thus can be aligned only at mod 1, 2, or 4 (can be only byte-, word-, 
or longword-aligned). To force another alignment, you would have to 
declare the record type and object in a library package (it would then be 
statically allocated, and there would be no restrictions). Alternatively, 
you would have to declare an access type that designates the record; the 
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designated object would be dynamically allocated, and, again, there would 
be no restrictions. 

You can achieve performance gains if you use alignment clauses to ensure 
that data is aligned on a "natural" boundary. By default, objects of type 
SHORT_SHORT_INTEGER, CHARACTER, and BOOLEAN, and objects 
of array and record types are aligned on byte boundaries; objects of type 
SHORT—INTEGER are aligned on a word boundaries; and objects of type 
INTEGER, as well as objects of floating-point, access, address, and task 
types, are aligned on longword boundaries. 

Alignment clauses could also be useful in a mixed-language environment, 
where you may want to force objects to particular boundaries. Note, 
however, that VAX hardware generally requires very little alignment; only 
a few instructions (and VAX Run-Time Library routines) need alignments 
(for example, queue instructions and ADAWI). You should also note 
that VAX Ada currently does not generate any queue or interlocked 
instructions. 

For additional information on efficient use of storage, see Chapter 8. 


3.3 Using Attributes to Determine the Size off Types and Objects 

The Ada language provides the SIZE attribute for determining the size of 
a type or an object (see Chapter 13 of the VAX Ada Language Reference 
Manual). However, because T'SIZE (where T is a type or a subtype) 
returns the minimum number of bits needed to represent an object of the 
type, and because O'SIZE (where O is an object) returns the actual number 
of bits allocated for the object, the results of T'SIZE and O'SIZE can often 
be quite different. For example, given the declaration 

type B00L17 is new BOOLEAN; 

the value of BOOL17'SIZE would be 1. One bit is the minimum amount 
of storage required for an object of type BOOL17. Even if you used a 
representation clause with the declaration of BOOL17, as in 

type B00L17 is new BOOLEAN; 
for B00L17'SIZE use 17; 

the value of BOOL17'SIZE would be 1; this attribute is not affected by 
representation clauses. 
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In VAX Ada, the size of a variable is always rounded up to a multiple of 
8 bits. In the case of discrete types, the size is always 8, 16, or 32 bits 
(padding bits are added to force at least byte alignments). (The size of a 
component object is also affected by packing and representation require¬ 
ments for the containing type.) Thus, without the representation clause, 
the size of an object of type BOOL17 would be 8; with the representation 
clause, the size would be 32 (17 bits to represent the object, plus 15 bits to 
round up to a longword). 

The VAX Ada attribute T'MACHINE_SIZE provides the same information 
for a type or subtype that O'SIZE provides for an variable. In other 
words, you can use T'MACHINE_SIZE to find the actual number of bits 
needed to represent a variable of type T (as opposed to the minimum 
number of bits returned by T'SIZE). T'MACHINE_SIZE is also affected by 
representation clauses, and returns a value rounded up to 8, 16, or 32 bits. 

T'MACHINE_SIZE of a base type can be less than, equal to, or greater 
than the T'SIZE of the same base type. Thus, the type and object declared 
in the following example 

type INT8 is range 0..255; 
for INT8'SIZE use 8; 

I: INT8; 

would produce the following results: 


INT8'SIZE 8 

INT8'MACHINE_SIZE 8 

I'SIZE 8 

INT8'BASE'SIZE 16 


The number of bits needed to represent the specified range values sym¬ 
metrically about 0 is 16, so SMALL_INT'BASE'SIZE is 16. Note that 
this value is greater than the values of SMALL_INT'MACHINE_SIZE, 
SMALL_INT'SIZE, and SMALL_INT_OBJ'SIZE. Also note that the values 
of SMALL_INT'MACHINE_SIZE and SMALL_INT_OBJ'SIZE are equal, 
as they should be. 

Table 3-6 lists a set of results for a variety of interesting cases. 
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Table 3-6: Results of Size Attributes for Various Types and 
Objects 


Declaration and Attributes 

type BOOL17 is new BOOLEAN; 
for BOOL17'SIZE use 17; 

B: BOOL 17; 

Type BOOL17'SIZE 
Object B'SIZE 

Type BOOL17 , MACHINE_SIZE 
Type BOOL17'BASE'SIZE 

type ET is range 0..255; 
for ET'SIZE use 8; 

E: ET; 

Type ET'SIZE 
Object E'SIZE 
Type ET'MACHINE_SIZE 
Type ET'BASE'SIZE 

type NET is ET range 0..7; 

NE: NET; 

Type NET'SIZE 
Object NE'SIZE 
Type NET'MACHINE_SIZE 
Type NET'BASE'SIZE 

type NT is new INTEGER range 0..255; 
for NT'SIZE use 8; 

N: NT; 

Type NT'SIZE 
Object N'SIZE 
Type NT'MACHINE_SIZE 
Type NT'BASE'SIZE 

C: CHARACTER; 

Type CHARACTER'SIZE 
Object C'SIZE 

Type CHARACTER'MACHINE_SIZE 
Type CHARACTER'BASE'SIZE 


Number of Bits 


1 

32 

32 

1 


8 

8 

8 

16 


3 

8 

8 

8 


8 

8 

8 

32 


7 

8 
8 
7 
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Table 3-6: (Cont.) Results of Size Attributes for Various 

Types and Objects 


Declaration and Attributes 


Number of Bits 


type BIT-ARRAY is array (1..10) of BOOLEAN; 


pragma PACK (BIT-ARRAY); 

BA: BIT-ARRAY; 

Type BIT—ARRAY'SIZE 10 

Object BA'SIZE 16 

Type BIT—ARRAY'MACHINE—SIZE 16 

Type BIT—ARRAY'BASE'SIZE 10 


3.4 Sharing Ada Storage with Non-Ada Programs 


When you compile a VAX Ada program, the compiler creates up to five 
contiguous areas of memory, called program sections (psects), to store 
information about the program. These program sections are named 
$CODE, $CONSTANT, $DATA, $ADDRESS, and $ZERO. The sections 
have the following characteristics and properties (see Table 3-7 for a 
definition of the properties): 

$CODE Contains machine instructions; has the properties PIC, 

USR, CON, REL, LCL, SHR, EXE, RD, NOWRT, NOVEC, 
ALIGN( 2). 

$CONSTANT Contains compile-time constants; has the properties PIC, 

USR, CON, REL, LCL, SHR, NOEXE, RD, NOWRT, 
NOVEC, ALIGN( 2). 

$DATA Contains static variables (library package data); has the 

properties PIC, USR, CON, REL, LCL, NOSHR, NOEXE, 
RD, WRT, NOVEC, ALIGN(2). 

$ADDRESS Contains address constants, exception vectors, and data 

produced by the compiler during the course of compi¬ 
lation; has the properties PIC, USR, CON, REL, LCL, 
NOSHR, NOEXE, RD, NOWRT, NOVEC, ALIGN( 2). 

$ZERO Contains compile-time constants whose value is com¬ 

pletely zero; has the properties PIC, USR, OVR, REL, 
LCL, SHR, NOEXE, RD, NOWRT, NOVEC, ALIGN( 9). 


Except for $CODE, the predefined program sections are not generated 
unless they are needed. 
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Table 3-7: Program Section Properties 


Class 

Meaning 

PIC/NOPIC 

Position independent or position dependent 

USR/LIB 

User or library 

CON/OVR 

Concatenated or overlaid 

REL/ABS 

Relocatable or absolute 

LCL/GBL 

Local or global scope 

SHR/NOSHR 

Shareable or nonshareable 

EXE/NOEXE 

Executable or nonexecutable 

RD/NORD 

Readable or nonreadable 

WRT/NOWRT 

Writeable or nonwriteable 

VEC/NOVEC 

Vectors or no vectors (protection) 

ALIGN 

Alignment 


When you link your program, the VAX/VMS Linker controls memory 
allocation and sharing according to the properties of each program section. 
The linker constructs an executable image by dividing the image into 
sections that have the same properties as their corresponding program 
sections. If you try to link two program sections that have the same 
name, but have different properties, the linker issues a warning. To avoid 
this warning, the VAX languages (including VAX Ada) have chosen the 
same properties for equivalent program sections. That is, the $CODE 
section generated by the VAX Ada compiler has the same properties as 
the $CODE section generated by the VAX PASCAL compiler, and so on. 
Thus, the linker allows you to construct a multilanguage image. (For more 
information on the VAX/VMS Linker, see the VAX/VMS Linker Reference 
Manual.) 

The only VAX Ada storage that you can explicitly share with non-Ada 
programs is storage allocated for objects declared in library packages. 

VAX Ada provides the pragmas IMPORT_OBJECT, EXPORT_OBJECT, 
and PSECT-OBJECT to allow such sharing. These pragmas are briefly 
defined as follows (a fuller definition appears in Chapter 13 of the VAX 
Ada Language Reference Manual). 

The syntax of the IMPORT-OBJECT and EXPORT—OBJECT pragmas is 

pragma IMPORT.OBJECT I EXPORT.OBJECT 

(internal_name [, external.designator] 

[, [SIZE =>] si;ae_designator]) ; 
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These pragmas are equivalent to the GLOBAL and EXTERNAL attributes 
in PASCAL, the GLOBALDEF and GLOBALREF attributes in PL/I, and 
the globaldef and globalref data types in C. You can also use them to 
share variables with VAX BLISS and MACRO. For example: 

-- Ada package that declares an imported 
-- integer object. 

package IMPORTOBJ is 
PAS.INT: INTEGER; 
pragma IMPORT_OBJECT(PAS_INT); 
end IMPORTOBJ; 

-- Ada main procedure that prints out the 
-- value of the imported object. 

with TEXT.IO; use TEXT.IO; 

with INTEGER_TEXT_IO; use INTEGER_TEXT_IO; 

with IMPORTOBJ; use IMPORTOBJ; 

procedure IMPORTPROC is 

begin 

put ("The value of PAS.INT is "); 
put (PAS_INT); 

end; 

-- VAX PASCAL module that declares a global integer 
-- (the equivalent of exporting an Ada object), 

-- and gives it an initial value. 

MODULE Pasobj (INPUT,OUTPUT); 

PROCEDURE Testpasobj; 

VAR 

Pas_int: [GLOBAL] INTEGER := 10; 

BEGIN 

END; 

END. 

This example illustrates the simple case of declaring an object in Ada and a 
variable in PASCAL and using the Ada IMPORT-OBJECT pragma and the 
PASCAL GLOBAL attribute to associate the name with a global symbol. 
The PASCAL module assigns the value 10 to the location referenced by 
the global symbol, and the Ada main procedure prints it out. 
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An analogous example of the use of EXPORT_OBJECT is 

-- PASCAL main program that prints out the value 
-- of the exported Ada object. 

PROGRAM Print_integer (INPUT,OUTPUT); 

VAR 

PAS.INT: [EXTERNAL] INTEGER; 

BEGIN 

WRITE('The value of Pas_int in PASCAL is '); 

WRITELN(PAS_INT); 

END. 

-- Ada package that declares the object to be 
-- exported. 

package EXPORT.INT is 

PAS.INT: INTEGER := 25; 
pragma EXPORT_OBJECT(PAS_INT); 
end EXPORT.INT; 

Here, PAS—INT and its initial value are exported from an Ada package 
to a PASCAL program. Note that if you want to use the LINK command 
(instead of the ACS LINK command—in other words, you are linking 
"from" PASCAL instead of "from" Ada), you must use the ACS EXPORT 
command to obtain the Ada object module from the program library. See 
Developing Ada Programs on VAX/VMS for more information. 

When sharing variables with VAX BLISS or VAX MACRO, you can use 
the size option of these pragmas to compare the size of the Ada object 
with the size expected by the external routine. The internal and external 
routines both define the same global literal and give as its value the size 
(in bytes) of the variable that is stored in the program section. (The size 
option causes the VAX Ada compiler to compute the size automatically.) If 
the two defined values of the global symbol are not equal, the VAX/VMS 
Linker issues an error. Thus, this feature provides some link-time size 
checking. 
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For example: 

! BLISS module that declares a 100-element longword array 
! named by the global symbol X and global literal X_SIZE 
! that correspond to the imported Ada object and size 
! designator of the same names. X_SIZE represents the amount 
! of storage allocated for X. 

i 

module INT.ARRAY (ident = '1-003') = 

begin 

global 

X : vector[100,long] ; 

global literal 

X_SIZE = /(allocation (X); 


end 

eludom 

-- Ada package that declares a 105-component array 
-- of integers (longwords), makes the object X known 
-- to the linker as a global symbol with the pragma 
— IMP0RT_0BJECT, and specifies a size designator 
-- with the same name as the BLISS global literal 
-- in order to obtain link-time consistency checking. 

package IMP0RT_ARRAY is 

X: array (1..105) of INTEGER; 
pragma IMP0RT_0BJECT(X, SIZE=>X_SIZE); 
end IMPORT.ARRAY; 

-- Ada main procedure that initializes the array 
-- object X (all components receive the value 10), 

-- and prints out the value of the 12th 
-- component. 

with TEXT_I0; use TEXT.IO; 
with INTEGER_TEXT_I0; use INTEGER_TEXT_I0; 
with IMPORT.ARRAY; use IMP0RT_ARRAY; 
procedure PRINT_C0MP0NENT is 

begin 

X := (1..105=>10); 
put ("The value of X(12) is "); 
put (X(12)); 
end PRINT.COMPONENT; 
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The BLISS and Ada code in this example compiles, but when linking 
is attempted, the linker issues an error message saying that X_SIZE is 
multiply defined (it finds two values for X_SIZE). (See also the example of 
size checking with the PSECT_OBJECT pragma at the end of this section.) 


The syntax of the PSECT_OBJECT pragma is 

pragma PSECT_OBJECT 

(internal_name [, psect.designator] 

[, [SIZE =>] si2;e_designator]) ; 

This pragma is provided primarily for use with FORTRAN or BASIC 
common blocks, PASCAL variables declared with the COMMON or 
PSECT attribute, and EXTERNAL variables in PL/I or variables declared 
with the extern keyword in C programs. You can also use it to share 
variables with VAX BLISS and VAX MACRO. 

Program sections established with the PSECT_OBJECT pragma have the 
following attributes (which are defined in Table 3-7). The alignment is 
the greater of the alignment required for the object being exported and 
ALIGN(2) (that is, longword alignment). 

PIC, USR, OVR, REL, GBL, SHR, NOEXE, RD, WRT, NOVEC, ALIGN 

This combination of attributes is the same as that used by other languages 
that allow you to allocate storage in common blocks (that is, overlaid 
program sections). (Other languages generally have longword alignment.) 
Note that PSECT_OBJECT program sections are overlaid and global. You 
cannot change program section attributes in VAX Ada. 

Unlike the VAX languages that allow you to store several variables 
in a particular common block, VAX Ada allows only one object to be 
allocated in a particular program section. If you want to share storage 
with FORTRAN common variables, for example, you must declare an Ada 
record variable in which each component of the record corresponds to one 
FORTRAN variable. 
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For example: 

C FORTRAN declarations: 

INTEGER DAY, MONTH, YEAR 
CHARACTER*20 NAME 

COMMON /BDATE/DAY, MONTH, YEAR / /NAME 

-- Corresponding VAX Ada declarations: 

type DATE is record 

DAY, MONTH, YEAR : INTEGER; 
end record; 

subtype NAME is STRING(1..20); 

BDATE : DATE; 

ACCTNAME : NAME; 

pragma PSECT.OBJECT (BDATE); 

pragma PSECT.OBJECT (ACCTNAME, "$BLANK"); 

This example illustrates storage allocation in two different program sec¬ 
tions. The FORTRAN COMMON statement declares two common blocks. 
One is named BDATE and contains the three integer variables DAY, 
MONTH, and YEAR. The second is a blank common block (whose name 
is $BLANK) and contains the character array variable NAME which has 
20 elements. 

The Ada record variable BDATE has three components that correspond to 
the three variables stored in the common block BDATE. The first PSECT— 
OBJECT pragma establishes the program section BDATE, which contains 
the record variable BDATE. (The name of the program section is the same 
as that of the variable because the psect designator parameter is omitted 
from the pragma statement.) The Ada variable ACCTNAME is a string of 
20 characters, which corresponds to the FORTRAN variable NAME. The 
second PSECT—OBJECT pragma specifies that storage for ACCTNAME 
is to be allocated in the program section $BLANK. Note that the psect 
designator must be a quoted string because the name contains a dollar 
sign ($). 

As with the IMPORT-OBJECT and EXPORT-OBJECT pragmas, you can 
use the SIZE option the PSECT—OBJECT pragma to gain some link-time 
consistency checking when sharing storage with VAX BLISS or MACRO 
routines. For example: 
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! Declaration of a named psect in VAX BLISS: 

PSECT 

NODEFAULT = X(OVERLAY, READ, WRITE, NOEXECUTE); 

OWN 

X: PSECT(X) VECTOR [10]; 

GLOBAL LITERAL 

XLEN = “/.ALLOCATION® ; 

-- Corresponding declaration in VAX Ada: 

type VECTOR is array(1..10) of INTEGER; 

X : VECTOR; 

pragma PSECT.OBJECT (X, SIZE => XLEN); 

The fragment of BLISS code declares a program section named X to store a 
vector of longwords. The GLOBAL LITERAL statement declares the global 
symbol XLEN to be equal to the allocation size of the variable X. The Ada 
code declares an array of integers (which are stored as longwords). The 
PSECT_OB]ECT pragma specifies that the array X is to be stored in the 
program section named X. Furthermore, the size option directs the Ada 
compiler to calculate the size of X and declare the global symbol XLEN to 
be equal to the size of X in bytes. At link time, the VAX/VMS Linker will 
check to see that the two declarations of XLEN are equal. If they are not, 
an error is issued. 
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Chapter 4 

Parameter Passing and Mixed-Language 

Programming 


All native-mode VAX languages, including VAX Ada, conform to a set 
of conventions—the VAX Procedure Calling Standard—that determine 
how routines are entered and exited, how parameters are passed, and how 
function results are returned. By conforming to this standard, VAX Ada 
allows calls from Ada subprograms to external (that is, non-Ada) routines 
and vice versa. 

This chapter reviews the calling standard and explains how to accom¬ 
plish mixed-language programming with VAX Ada: Section 4.1 gives 
general information on the call stack and shows how calls are executed; 
Section 4.2 describes the parameter-passing mechanisms used by VAX 
Ada; Section 4.3 explains how VAX Ada function results are returned; 
and Section 4.4 discusses and shows the use of the VAX Ada import and 
export pragmas. 

The full text of the VAX Procedure Calling Standard is in the VAX/VMS 
manual. Introduction to System Routines. Chapter 13 of the VAX Ada 
Language Reference Manual gives the syntax and usage rules for the VAX 
Ada import and export pragmas. You should be familiar with the material 
in these two manuals before trying to use the information in this chapter. 

Note that the calling standard uses the term procedure to mean any routine 
entered by a VAX CALL instruction. To avoid confusion with Ada's 
definition of a procedure, this manual uses the term routine. 
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4.1 The Call Stack 


The call stack is a temporary area of storage allocated by the system 
for each user process. When an Ada program (or a program written in 
any language that conforms to the calling standard) is executing, the 
VAX hardware uses the call stack to maintain information about each 
routine call in the program. Thus, whenever an Ada program calls a 
routine (which could be an Ada subprogram or an imported non-Ada 
subprogram), or an Ada subprogram is exported and called by a non-Ada 
routine, the hardware creates two structures—an argument list and a call 
frame. Depending on the CALL instruction that implements the call, the 
argument list is placed on the process call stack (CALLS), or prebuilt and 
given as an operand (CALLG); the call frame is always placed on the 
stack. (Note that the choice of stack depends on the mode in which your 
process is executing; see the VAX-11 Architecture Reference Manual for 
more information.) 

The contents of the call stack during a routine call (CALLS) are shown in 
Figure 4-1; the argument list and call frame are described in Sections 4.1.1 
and 4.1.2. 
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Figure 4-1: A Call Stack at Run Time 
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Figure 4-1 (Cont.): A Call Stack at Run Time 
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4.1.1 The Argument List 


Each time a VAX Ada subprogram calls or is called by another subprogram 
or non-Ada routine, an argument list is passed. The argument list is a 
sequence of longword (32-bit) entries that is pointed to by a register called 
the argument pointer (AP). 

The first longword entry always contains, in its low byte, an unsigned 
integer count of the number of arguments in the list. Each succes¬ 
sive longword entry represents one parameter, and, depending on the 
parameter-passing mechanism being used, can be a 32-bit value, an ad¬ 
dress of an object, or an address of a descriptor. Figure 4-2 illustrates the 
format of an argument list; parameter-passing mechanisms are explained 
in Section 4.2. 

Figure 4-2: An Argument List 
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4.1.2 The Call Frame 

For any called routine, the hardware-created call frame contains 

• A pointer to the call frame of the previous (calling) routine. This 
pointer is called the saved frame pointer (FP). 

• The saved argument pointer (AP) of the previous (calling) routine. 

• The address in storage of the point at which the routine was called; 
that is, the address of the instruction following the call to the current 
routine. This address is called the program counter (PC), or saved PC. 
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• The saved contents of some of the general registers and other control 
information (such as the condition codes in the processor status word, 
or PSW, which is the low-order word of the processor status longword, 
or PSL). Based on a mask specified in the control information, the 
system restores these registers when control returns to the caller. 

Figure 4-3 illustrates a call stack with three call frames: routine A calls 
routine B, and routine B calls routine C. When a routine finishes executing 
(in Ada, when a function or procedure reaches a return statement or when 
control reaches the end of a procedure), the system uses the frame pointer 
in the call frame of the current routine to locate the call frame of the 
previous (calling) routine. The system then removes the call frame of the 
current routine from the stack, and returns control to the calling routine 
(at the point of the saved PC). 

Figure 4-3: A Call Stack 
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4.2 VAX Parameter-Passing Mechanisms and VAX Ada 
Parameter-Passing Semantics 

The VAX Procedure Calling Standard defines three mechanisms by which 

parameters can be passed: 

• By immediate value—The argument list entry is the value of the actual 
parameter. The argument can be at most 32 bits in length. If the 
called subprogram or routine expects fewer than 32 bits, it accesses the 
low-order bits and ignores the high-order bits. 

• By reference—The argument list entry is the address of the actual 
parameter value. 

• By descriptor—The argument list entry is the address of a descriptor of 
the actual parameter; that is, the entry is the address of a data structure 
that describes the parameter. 


The Ada language defines two kinds of mechanisms, or semantics, for 
parameter passing: copy-in/copy-back semantics and reference semantics. 
(Note the use of the word "semantics" to avoid confusion with the VAX 
parameter-passing mechanisms.) 

For parameters of mode in or in out, copy-in/copy-back semantics 
involves copying the value of the actual parameter into its associated 
formal parameter; for parameters of mode in out or out, copy-in/copy- 
back semantics involves copying the value of the formal parameter back 
into the actual parameter. Reference semantics involves no copies: any 
modifications to a formal parameter imply the same modifications to the 
associated actual parameter. 

The following sections detail the VAX Ada implementation of the copy- 
in/copy-back semantics used for scalar and access type parameters, and 
explain which kind of semantics has been chosen for array, record, access, 
task, and address types. (Parameters of private or limited private types are 
passed according to the semantics and mechanisms of their corresponding 
full type declarations.) In all cases, the semantics are explained in terms 
of the VAX parameter-passing mechanisms; all Ada parameters are (by 
default) passed by either the VAX reference or descriptor mechanisms. 

Note that the Ada semantics and VAX mechanisms described in the fol¬ 
lowing sections are used in all Ada compiled code—both in exported 
subprograms and in programs written entirely in Ada. The VAX mecha¬ 
nisms are also the default mechanisms for parameters passed to imported 
subprograms (non-Ada routines). (The default mechanisms for imported 
routines can be overridden, as explained in Section 4.4.2.) 
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4.2.1 Copy-In/Copy-Back Semantics 


The Ada language requires copy-in/copy-back semantics for scalar, access, 
and address types (see Chapter 6 of the VAX Ada Language Reference 
Manual ). In most cases, such as when a scalar parameter is passed, the 
actual parameter is unpacked and byte-aligned. The steps for copy-in/ 
copy-back semantics performed by the compiler-generated code are as 
follows: 

Before the subprogram call: 

1. If the formal parameter has mode in or in out, a check is performed 
to ensure that the actual parameter value satisfies the constraints 

of the formal parameter. If the actual parameter fails this check, 
CONSTRAINT-ERROR is raised. 

2. A reference to the actual parameter (its address) is placed in the 
argument list. 

During the subprogram call: 

3. A temporary, local variable is allocated to hold the formal parameter. 

4. If the formal parameter has mode in or in out, the value at the actual 
parameter address is copied to the formal parameter. 

5. The subprogram is executed. 

6. If the formal parameter has mode in out or out, the value of the formal 
parameter is copied to the location at the actual parameter address. 

There are two special cases of this calling sequence. If the actual param¬ 
eter is packed (and thus not byte-aligned), an unpacked, byte-aligned 
temporary variable is created to hold the actual value. The creation of 
this temporary variable occurs before step 1. In step 2, the address placed 
in the argument list is the address of the temporary variable. After the 
subprogram call, the value of the temporary variable is copied back into 
the actual parameter. 

The second special case occurs if the formal parameter has mode in out or 
out and the constraints of the formal parameter are not known (at compile 
time) to satisfy the constraints of the actual parameter. Once again, a 
temporary variable is created to hold the actual parameter value, and 
steps 1 and 2 apply to the temporary variable. After the subprogram call, 
a check is performed to ensure that the value at the temporary variable 
address satisfies the constraints of the actual parameter. If it does not, 
CONSTRAINT-ERROR is raised. If the constraints are satisfied, the value 
at the temporary variable address is copied back to the actual parameter. 

These two special cases can occur together, as well as separately, for any 
formal parameter. 
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4.2.2 Scalar Type Parameters 


Scalar values (enumeration, integer, floating-point, and fixed-point) are 
passed by the VAX reference mechanism using Ada copy-in/copy-back 
semantics. 


4.2.3 Array Type Parameters 

Array parameter passing is determined by the kind of array being passed: 

• A string is any one-dimensional array of a discrete type whose com¬ 
ponents occupy successive, unsigned bytes. (In other words, strings 
are arrays whose component types include, but are not limited to, the 
predefined type CHARACTER.) 

• A bit string is any one-dimensional array of a discrete type whose 
components occupy successive single bits. 

• A bit array is any array whose components are not byte aligned, yet 
which is also not a bit string. 

• A packed array is any array which has been declared with (and affected 
by) pragma PACK (see Section 3.2.1). 

• A packable array is any bit string, or any packed array whose compo¬ 
nent type is a packable array (note that not all bit arrays are packable). 


Arrays are usually passed by the VAX reference mechanism using Ada 
reference semantics. However, they are passed by the VAX descriptor 
mechanism (using Ada reference semantics) in the following cases: 

• When the formal parameter specifies a constrained bit string or bit 
array that is packable. 

• When the formal parameter specifies a constrained bit string or bit 
array that is not a first-named subtype. 

• When the formal parameter specifies an unconstrained array type. 


Descriptor classes are chosen by the compiler based on how much is 
known about the array type at compile time. In general, the defaults 
are those shown in Table 4-1. Additional descriptor information needed 
for passing arrays to imported subprograms is given in Section 4.4.2. 

See Section 3.1.5 for information on how arrays are represented, and 
Section 3.2 for an explanation of how to control that representation. 
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Table 4-1: Default Descriptor Classes Used by VAX Ada for 
Array Parameter Passing 


Class 

Associated Ada Type 

DSCSK—CLASS—SB 1 

Any string where the compiler can determine that 
the number of components will not exceed 65,535. 

DSC$K_CLASS_UBSB 

1 Any bit string where the compiler can determine 

that the number of components will not exceed 
65,535. 

DSC$K_CLASS_UBA 

Any bit array or any other bit string. 

DSC$K_CLASS_A 

Any other array. (CONSTRAINT-ERROR is raised 
if DSC$W_LENGTH is inadequate.) 

The descriptor classes DSC$K_CLASS_SB and DSC$K_CLASS_UBSB are variants of the VAX 
DSC$K_CLASS_S and DSC$K_CLASS_UBS descriptors; they have the same fields, plus additional 
longword fields to hold the lower and upper bounds of the array. All of the VAX descriptors are 
illustrated in the Introduction to System Routines. 


4.2.4 Record Type Parameters 

Records are normally passed by the VAX reference mechanism using Ada 
reference semantics. The address in the argument list always refers to a 
byte-aligned representation. If the actual parameter is a record that is a 
packed component of a composite type, the compiler creates a temporary 
copy that is unpacked and byte-aligned. The address in the argument list 
then refers to the temporary copy. This gives the effect of Ada copy-in/ 
copy-back semantics. 

If the record type has discriminants with defaults, the calling routine 
passes additional information in the argument list in certain cases. That is, 
if the formal parameter is unconstrained and has mode in out or out, the 
calling routine provides a "constrainedness bit." The constrainedness bit 
indicates whether the discriminants of the actual parameter are allowed to 
be changed. 

Constrainedness bits are passed by immediate value in the last longword 
in the argument list. A subprogram can have up to 32 formal parameters 
that require a constrainedness bit: each bit in the longword corresponds to 
one formal parameter. If fewer than 32 constrainedness bits are needed, 
the lowest-order bits are used. 
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4.2.5 Access Type Parameters 

Access values are passed by the VAX reference mechanism using copy-in/ 
copy-back semantics. The rules for passing access values are the same 
as those for passing scalar values (see Section 4.2.2), except that any 
necessary constraint checking is done on the object designated by the 
access value rather than on the access value itself. 


4.2.6 Task Type Parameters 

Values of task types are passed by the VAX reference mechanism using 
Ada reference semantics. 


4.2.7 Address Type Parameters 

Values of address types (values of type SYSTEM.ADDRESS and its 
derivatives) are passed by the VAX reference mechanism using Ada 
copy-in/copy-back semantics. 


4.3 Function Return Values 

The VAX Procedure Calling Standard defines the interface that must 
be used to return function values in a mixed-language application. The 
standard defines—and VAX Ada generally follows the definition of—a 
function as a routine that returns a single value according to the following 
conventions: 

1. If the function value requires 32 bits or less, it is returned in register 
RO. 

2. If the function value requires from 33 to 64 bits, the low-order bits of 
the value are returned in register RO, and the high-order bits of the 
value are returned in register Rl. 

3. If the function value requires more than 64 bits, the calling routine 
passes an extra parameter—an address—as the first argument in the 
argument list. The address can point to either the storage for the value 
or to a descriptor. 

If the maximum length of the function value is known, the calling 
program allocates the required storage and passes either the address 
of the storage or a descriptor. If the maximum length is not known, 
the calling program can allocate a descriptor and pass its address. The 
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called function allocates storage for the function value and updates the 
contents of the descriptor. 

The interpretation of these conventions for each of the VAX Ada types 
is given in the following sections. Information on the representation and 
storage of values of the various Ada types is given in Chapter 3. 


4.3.1 Scalar, Access, Task, and Address Type Results 

Because they require a maximum of 32 bits, values of enumeration, 
integer, fixed-point, and F_floating-point types are returned in register RO. 
Because they require 64 bits, values of floating-point types that use the 
D_floating or G—floating representation are returned in registers RO and 
Rl. Values of floating-point types that use the H_floating representation 
need 128 bits; thus, the calling routine must provide the address of a 
location that will receive the function result, and the address is passed as 
the first argument in the argument list. 

Values of any access, task, or address type are returned in register RO. 

Note that if the allocation of an enumeration or integer type is less than 
32 bits, the returned value is zero- or sign-extended (as appropriate) to a 
clean 32-bit representation. 


4.3.2 Array Type Results 

The methods by which array function results are returned depend on 
whether or not the array is constrained. 

If the type of the function value is a constrained array and all of the 
following conditions apply, then the function value is returned in register 
RO or in registers RO and Rl: 

• The array bounds and the component size are known at compile time. 

• The size of the array is 64 or fewer bits (returned in RO if 32 or fewer 
bits; otherwise, returned in RO and Rl). 

• The array is not a string type (see Section 4.2.3). 

If the storage size for the array is not known at compile time or if the size 
is known to be greater than 64 bits, the calling routine must pass—as the 
first argument in the argument list—the address of a location in memory 
to receive the function value. (This kind of function result passing is called 
the extra parameter method.) 

Note that string types are never returned in registers. However, if they are 
constrained, they can be returned with the extra parameter method. 
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If the function return value is of an unconstrained array type (including 
unconstrained string types) or an unconstrained type with discriminants, 
the calling routine must pass the address of an area control block as the 
first argument in the argument list. The area control block is described 
and illustrated in Figure 4-4. 

Figure 4-4: Area Control Block Used in Returning Some 
Function Results 
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1. If LENGTH is zero, then no storage has been previously allocated, and POINTER is 
undefined. The called function allocates storage sufficient for the value to be returned 
using the given ZONE. LENGTH is then set to the size of the block of the storage 
allocated. 

2. If LENGTH is nonzero, then storage has been previously allocated, and POINTER is set 
to the address of that block of storage. The called function can either reuse the storage 
(if it is sufficient), or it can deallocate the storage and allocate new storage. (The called 
routine has the option of doing either if the previously allocated storage is sufficient.) 

3. If ZONE is null, then default process dynamic memory is used. 

If ZONE is -1, then there is no zone associated with the storage, and the calling routine 
guarantees that the storage described by LENGTH and POINTER is sufficient for the 
return value. 

Otherwise ZONE is the address of a zone control block. 

Note that a single storage area control block can be used in multiple calls without explicit 
freeing between calls. Also note that by allowing the calling routine to allocate storage when it 
deems appropriate, the overhead of dynamic memory management is avoided. 


ZK-3021-84 


Note that in the case of an unconstrained array type, the area control block 
is concatenated with an array descriptor. The appropriate descriptor class 
(DSC$K_CLASS_UBSB, DSC$_CLASS_UBA, DSC$K_CLASS_SB, or 
DSC$K_CLASS_A) is chosen according to the rules given in Section 4.2.3 
for passing parameters of array types. 
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The calling routine need not initialize the descriptor or allocate storage for 
the value. The called function allocates storage in the appropriate zone 
and fills in the descriptor that refers to the value. The calling routine must 
release the storage for the value after it has been used. 


4.3.3 Record Type Results 

For a simple record type whose size is 32 bits or less, the function value 
is returned in RO. If the record size is 33 to 64 bits, the function value 
is returned in RO and Rl. (A simple record is one that has no variants 
and that has components and subcomponents whose constraints are 
static. Note that simple records can have discriminants. See Chapter 13 
of the VAX Ada Language Reference Manual for a complete definition of 
simple record types and subtypes; see Chapter 4 of the VAX Ada Language 
Reference Manual for a definition of static.) 

For a record type over 64 bits (including large, simple records and con¬ 
strained records), the calling routine must pass the address of a location 
to receive the function value as an extra parameter in the argument list 
(the calling routine must use the extra parameter method). The function 
returns the result at that location. See Section 3.1.6 for information on 
how to estimate the storage size of records. 

For a function value of an unconstrained record type with discriminants 
with defaults, the caller must pass an area control block for the called 
function to use in returning the result. The caller is responsible for 
releasing the storage for that value after it has been used. (The area 
control block is described and illustrated in Figure 4-4, Section 4.3.2.) 


4.4 Using the Import and Export Pragmas 

To allow you to accomplish mixed-language programming, VAX Ada 
provides a set of import and export pragmas. The use of these pragmas is 
described in this section. 
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4.4.1 Exporting Ada Subprograms 


VAX Ada provides the EXPORT-PROCEDURE and EXPORT- 
FUNCTION pragmas to enable you to call Ada subprograms from pro¬ 
grams written in another language. When calling an Ada subprogram 
from a non-Ada routine, you must ensure that the parameters are passed 
in the form required by the Ada subprogram. 

NOTE 

Some VAX languages allow optional and/or default parameters. 

For VAX Ada, calls from non-Ada code to exported subpro¬ 
grams must always supply all parameters that are declared 
as formal parameters. In particular, an actual value must be 
supplied even when a default expression is given for a formal 
parameter in the Ada subprogram specification. 

Detailed explanations of the syntax and usage rules for these pragmas 
are given in Chapter 13 of the VAX Ada Language Reference Manual. For 
convenience, the syntax is summarized here: 

pragma EXPORT.PROCEDURE I EXPORT.FUNCTION 
(internal_name [, external_designator] 

[, [PARAMETER.TYPES =>] (parameter.types)] 

[, [RESULT_TYPE =>] (type_mark)]); 

-- for EXPORT_FUNCTION only 

internal_name :: = [INTERNAL =>] identifier 

external_designator ::= [EXTERNAL =>] identifier 
I [EXTERNAL =>] string_literal 

parameter_types ::= null I type_mark {, type_mark> 

Note that if you export an Ada subprogram that would normally receive 
parameters passed by descriptor class DSC$K_CLASS_SB (see Section 
4.2.3), the Ada compiler ensures that parameters passed by descriptor 
class DSC$K_CLASS_S are also accepted. When a DSC$K_CLASS_S 
descriptor is received by the exported (Ada) subprogram, the descriptor 
bounds are defined as 1..N, where N is the length of the string. The 
compiler also ensures that DSC$K_CLASS_UBS descriptors are accepted 
in place of DSC$K_CLASS_UBSB descriptors, with implicit bounds 
assumed in the same way. As a result, a slight performance penalty is 
imposed on exported subprograms where such descriptors are involved. 
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The following simple example shows the exporting of a VAX Ada subpro¬ 
gram to a VAX PASCAL main program: 

PROGRAM Use.swap (INPUT,OUTPUT); 

Var 

X,Y: INTEGER; 

PROCEDURE Swap (VAR Swapl,Swap2: INTEGER); 

EXTERNAL; 

Begin 

(* Give X and Y values *) 

SWAP(X,Y); 

End. 


procedure SWAP (A.B: in out INTEGER) is 
TEMP: INTEGER; 
begin 

TEMP := A; 

A := B; 

B := TEMP; 
end; 

pragma EXPORT.PROCEDURE (SWAP); 

Alternatively, procedure SWAP could be exported from a package: 

package SWAP.ROUTINES is 

procedure SWAP (A.B: in out INTEGER); 
pragma EXPQRT_PROCEDURE (SWAP); 

end SWAP.ROUTINES; 

package body SWAP.ROUTINES is 

procedure SWAP (A.B: in out INTEGER) is 
TEMP: INTEGER; 
begin 

TEMP := A; 

A := B; 

B := TEMP; 
end; 

end SWAP.ROUTINES; 

Note that when you export an Ada subprogram to a non-Ada main 
program, you must use the ACS EXPORT command to prepare the 
subprogram for linking. See Developing Ada Programs on VAX/VMS for 
more information. 
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As an example of exporting an Ada subprogram where descriptor passing 
mechanisms are involved, the following exported Ada function takes a 
string and a character, and returns the index of the first string component 
that matches the character: 

function NFIND (STR: STRING; 

C : CHARACTER) return INTEGER is 

begin 

for I in STR'RANGE loop 
if STR(I) = C then 
return I; 
end if; 
end loop; 

-- if no match 

return 0; 
end; 

pragma EXP0RT_FUNCTI0N(NFIND); 

The Ada function expects the string STR parameter to be passed by 
DSC$K_CLASS_SB descriptor, and the character C to be passed by ref¬ 
erence. (This information is displayed for exported subprograms by the 
compiler when the COMPILATION-NOTES warning option is used on 
the ADA command or on the ACS COMPILE and RECOMPILE com¬ 
mands. See Developing Ada Programs on VAX/VMS for more information.) 

Because the Ada function is exported, it will also accept the string STR if 
the string is passed by DSC$K_CLASS—S descriptor. 

The following FORTRAN routine uses (imports) the Ada function: 

CHARACTER*(12) X 
CHARACTER*(1) B 
X = '1234 6789' 

B = ' ' 

N = NFIND (X, °/,REF(B)) 

type *, B, N 

end 

In FORTRAN, string parameters are usually passed by descriptor using the 
DSC$K_CLASS—S descriptor. This parameter-passing mechanism applies 
to both X and B in the example. However, B must be passed by reference 
to the Ada routine (the CHARACTER type is an enumeration type, which 
is, by default, passed by reference in VAX Ada). The %REF mechanism 
specifier causes B to be passed by reference. 
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4.4.2 Importing External Routines 


VAX Ada provides the IMPORT-PROCEDURE, IMPORT-FUNCTION, 
and IMPORT—VALUED—PROCEDURE pragmas to enable you to call 
external (non-Ada) routines. Detailed explanations of the syntax and 
usage rules for these pragmas are given in Chapter 13 of the VAX Ada 
Language Reference Manual. For convenience, the syntax is summarized 
here: 

pragma IMPORT.PROCEDURE 

I IMPORT_VALUED_PROCEDURE | IMPORT.FUNCTION 
(internal_name [, external_designator] 

[, [PARAMETER_TYPES =>] (parameter_types)] 

[, [RESULT_TYPE =>] type_mark] 

-- for IMPORT.FUNCTION only 
[, [MECHANISM =>] mechanism]; 

internal_name :: = [INTERNAL =>] identifier 
I [INTERNAL =>] string_literal 
— An operator designator, which 
-- can be used only for 
-- IMPORT.FUNCTION 

external_designator ::= [EXTERNAL =>] identifier 

I [EXTERNAL =>] string_literal 

parameter_types ::= null | type_mark {, type_mark> 

mechanism ::= mechanism_name 

I (mechanism_name {, mechanism_name>) 

mechanism name ::= VALUE 
I REFERENCE 

I DESCRIPTOR [([CLASS =>] class-name)] 

class_name :: = UBS I UBSB I UBA I S | SB | A I NCA 

Each VAX language and VAX/VMS routine has default conventions that 
determine how its parameters must be passed. When calling (importing) a 
non-Ada routine, you must ensure that each parameter is passed with the 
mechanism required by that routine. The VAX language user's guides and 
VAX/VMS documentation of system routines provide this information. 

The import pragmas assume by default that parameters are passed using 
the mechanisms described in Sections 4.2.2 through 4.2.7. To override 
these mechanisms, you may specify a mechanism option—VALUE, 
REFERENCE, or DESCRIPTOR—with the import pragmas. Use of one 
of these options forces the choice of the immediate value, reference, or 
descriptor mechanism defined in the VAX Procedure Calling Standard 
(see also Section 4.2). Thus, after you determine how an external routine 
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expects its parameters to be passed, you can specify the appropriate 
mechanism name on the import pragma to ensure that the parameter¬ 
passing conventions match. The sections that follow give the rules for 
using each mechanism. 

Note that when importing VAX/VMS system routines, you often have 
to give null (or zero) values for optional parameters. VAX Ada provides 
the attribute NULL-PARAMETER and the constant SYSTEM.ADDRESS- 
ZERO to allow you to specify such values. NULL—PARAMETER, for 
example, is useful for specifying null values for composite types such as 
strings or records. Chapter 13 of the VAX Ada Language Reference Manual 
describes the types provided by package SYSTEM, as well as the rules 
for using the NULL—PARAMETER attribute. Chapter 5 of this manual 
discusses and gives examples of optional parameters in calls to system 
routines. 


4.4.2.1 The VALUE Mechanism Option 

If you specify VALUE as a mechanism name, the compiler passes the ac¬ 
tual parameter by immediate value in the argument list. This mechanism 
is valid for values that have a compile-time size of 32 bits or less. Thus, 
it is valid for discrete types and access types. It is also valid for values of 
the predefined type SYSTEM.ADDRESS or any types derived therefrom. 
You can use VALUE to pass bit strings and simple records of up to 32 
bits (see Section 4.2.3 for a definition of bit strings and Section 4.3.3 for a 
description of simple records). 

Note that you can use VALUE only if the corresponding formal param¬ 
eter has mode in, or if the parameter is the first parameter in pragma 
IMPORT—VALUED—PROCEDURE. (The first parameter in pragma 
IMPORT—VALUED—PROCEDURE has mode out; see Chapter 13 of 
the VAX Ada Language Reference Manual and Chapter 5 of this manual.) 


4.4.2.2 The REFERENCE Mechanism Option 

The REFERENCE mechanism causes the address of an actual parameter to 
be passed in the argument list. This mechanism can be used to pass actual 
parameters of any type. However, if a non-byte-aligned actual parameter 
is passed, the exception CONSTRAINT—ERROR is raised. 

You can use REFERENCE even in cases where a descriptor or additional 
information is usually passed (see Sections 4.2.3 and 4.2.4). However, 
when you use REFERENCE in such cases, you must find a way to pass the 
additional information to the external routine. For example, in VAX Ada 
you would normally pass an unconstrained array parameter by descriptor, 
where the descriptor contains the information about the array bounds. 
Thus, if you import a routine written in FORTRAN (where all arrays are 
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passed by reference), and pass an unconstrained array parameter, you 
must pass the array bounds as an additional formal parameter. 

For example, suppose the following function is declared in FORTRAN: 

FUNCTION INNERPROD (A, B, N) 

C This routine multiplies two one-dimensional arrays, 

C element-by-element, then sums the products. Declare A 
C and B as arrays of real numbers. 

C 

REAL A(N), B(N) 

SUM = 0 

DO 100 I = 1, N 

SUM = SUM + A(I) * B(I) 

100 CONTINUE 

INNERPROD = SUM 

RETURN 

END 

A and B are adjustable arrays whose bounds are passed as a subpro¬ 
gram argument. To call this routine from Ada, you could declare two 
unconstrained array parameters to correspond to A and B. By passing the 
integer parameter N to correspond to the array length parameter, N, in 
the FORTRAN function, you could then pass the Ada arrays by reference 
without losing information. The declarations and function call in VAX 
Ada would be as follows: 

type ARRAY1 is array (INTEGER range <>) of FLOAT; 

function INNERPROD (A, B : ARRAY1, N : INTEGER) return FLOAT; 

pragma INTERFACE (FORTRAN, INNERPROD); 

pragma IMPORT.FUNCTION (INNERPROD, MECHANISM => REFERENCE); 

Q, T : ARRAYKl. .100) ; 

P : FLOAT; 

P := INNERPROD (Q, T, Q'LENGTH); 

Note that because Q and T are of the same length, either Q'LENGTH or 
T'LENGTH can be passed to INNERPROD as actual parameters for N. 
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4.4.2.3 The DESCRIPTOR Mechanism Option 

The DESCRIPTOR mechanism causes the compiler to pass the address 
of a string, array, or scalar descriptor, as described in the VAX Procedure 
Calling Standard (see the Introduction to System Routines). The VAX Ada 
compiler generates the descriptor and supplies the necessary information. 

Parameters of all scalar types, array types, and access types can be passed 
by descriptor; parameters of record and task types cannot. 

The calling standard defines various descriptor classes that can be used 
for passing parameters of different VAX data types. For certain array pa¬ 
rameters, the VAX Ada compiler automatically generates a subset of these 
descriptors (see Section 4.2.3). For parameters that must be passed by 
descriptor to an imported routine, the DESCRIPTOR mechanism name can 
be given with an optional class name argument that specifies the particu¬ 
lar descriptor to be used. If you use the DESCRIPTOR mechanism name, 
but omit the class name, the VAX Ada compiler chooses an appropriate 
default class depending on the Ada parameter type. 

The following example shows the use of the IMPORT-PROCEDURE 
pragma to call the VAX Run-Time Library routine OTS$CVT_L_TZ, 
where a string is passed by descriptor. The routine converts a longword 
(in this case an Ada INTEGER) to a hexadecimal ASCII text string. It 
requires two parameters: an integer passed by reference, and a text string 
passed by descriptor using descriptor class S. 

procedure SHOW.CONVERT is 

type INPUT.INT is INTEGER range 0..INTEGER'LAST; 

INTVALUE : INPUT.INT; 

HEXSTRING : STRING(1. .11) ; 

procedure C0NVERT_T0_HEX (I : in INPUT.INT; HS : out STRING); 
pragma INTERFACE (RTL, C0NVERT_T0_HEX); 
pragma IMPORT_PROCEDURE (C0NVERT_T0_HEX, 

"OTS$CVT_L_TZ", 

(REFERENCE, 

DESCRIPTOR (CLASS => S))); 


begin 

C0NVERT_T0_HEX (INTVALUE, HEXSTRING); 

end; 
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The formal parameter I is an INTEGER that is passed by reference. The 
formal parameter HS is an unconstrained string. By default, unconstrained 
strings are passed using descriptor class DSC$K_CLASS_SB. In this case, 
passing the parameter HS with class DSC$K_CLASS_SB would mean 
passing extra information (the string bounds) that the Run-Time Library 
routine does not need. Thus, for efficiency, the mechanism argument of 
the IMPORT-PROCEDURE pragma specifies that the second parameter 
(HS) be passed by descriptor using class DSC$K_CLASS—S. (Note that 
since the formal parameter HS is unconstrained, an actual parameter of 
any length can be passed to the routine.) 

Table 4-2 lists the default descriptor classes generated for imported 
parameters specified with the DESCRIPTOR mechanism. Definitions of 
the VAX Ada string, bit-string, and bit-array types are given in Section 
4.2.3. 


Table 4-2: 

Default Descriptor Class Names Used for the 
DESCRIPTOR Mechanism 

Class Name 

Use 

UBS 

UBSB 

If the parameter is a bit string. (UBS is used only for a 
constrained bit string whose lower bound is 1.) 

A 

NCA 

If the parameter is any array type except a bit string or a bit 
array. 

S 

SB 

If the parameter is of an integer, enumeration, floating-point, 
fixed-point, access, or address type, or if it is an array of 
unsigned bytes. (S is used only for a constrained string 
whose lower bound is 1, or any nonarray type.) 

UBA 

If the parameter is of any array type. 


A more detailed summary of the class names and characteristics of the 
requisite Ada types to which the classes apply is given in Table 4-3. 
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Table 4-3: Type Requirements for Descriptor Classes Used 
by VAX Ada in Importing Routines 


Class 


UBS 


UBSB 


UBA 


Name Requisite Characteristics of 

Ada Formal Parameter Type 

Unaligned bit string: the base type of the formal parameter 
must be a one-dimensional array of 1-bit components. 

If the formal array parameter is constrained, then the lower 
bound must be equal to 1. If the base type is not a VAX Ada 
bit-string type (see Section 4.2.3 for a definition of bit strings), 
then a run-time descriptor check occurs to ensure that the 
actual array parameter has no more than 65,535 components. 
If this check fails, then CONSTRAINT_ERROR is raised. 

Unaligned bit string with arbitrary bounds: the base type 
of the formal parameter must be a one-dimensional array of 
1-bit components. 

If the base type is not a VAX Ada bit-string type (see Section 
4.2.3 for a definition of bit strings), then a run-time descriptor 
check occurs to ensure that the actual array parameter has 
no more than 65,535 components. If this check fails, then 
CONSTRAINT-ERROR is raised. Note that the value of 
A'FIRST'POS need not be equal to 1. 

Unaligned bit array: the base type of the formal parameter 
must be an array. 

A run-time descriptor check occurs to ensure that the size of 
each component of the actual parameter requires no more 
than 65,535 bits. If this check fails, then CONSTRAINT- 
ERROR is raised. 

You normally use this descriptor when the formal parameter 
array components are unaligned (the formal parameter 
type has been declared with pragma PACK). If the array 
components are byte-aligned, use descriptor class A. 
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Table 4-3: (Cont.) Type Requirements for Descriptor 

Classes Used by VAX Ada in Importing 
Routines 


Class Name Requisite Characteristics of 

Ada Formal Parameter Type 

S Scalar or access type, or string: the base type of the formal 

parameter must be a one-dimensional array of 8-bit unsigned 
components (a VAX Ada string type; see Section 4.2.3 for a 
definition of string types), a scalar, or an access type. 

If the parameter is a constrained array, then the lower bound 
must be equal to 1. For an array type that is not a VAX 
Ada string type, a run-time descriptor check occurs to ensure 
that the actual array parameter has no more than 65,535 
components. If this check fails, then CONSTRAINT-ERROR 
is raised. 

For a scalar or access type, the DTYPE field of the descriptor 
is filled in as shown in Table 4-4. 

SB String with arbitrary bounds: the base type of the formal 

parameter must be a one-dimensional array of unsigned 8-bit 
components (a VAX Ada string type; see Section 4.2.3 for a 
definition of string types). 

For an array type that is not a VAX Ada string type, a run¬ 
time descriptor check occurs to ensure that the actual array 
parameter has no more than 65,535 components. If this check 
fails, then CONSTRAINT-ERROR is raised. 
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Table 4-3: 

(Cont.) Type Requirements for Descriptor 

Classes Used by VAX Ada in Importing 
Routines 

Class Name 

Requisite Characteristics of 

Ada Formal Parameter Type 

A 

Contiguous array: the base type of the formal parameter 
must be a byte-aligned array type (that is, an array that 
starts on a byte boundary) with byte-aligned components 
or 1-bit components. (This excludes any array of packable 
components whose component size is not 1, 8, 16, or 32 bits 
and for which the pragma PACK is given.) 


If the array type has 1-bit components, a run-time descriptor 
check is performed to ensure that the actual array parameter 
is byte-aligned. If this check fails, then CONSTRAINT- 
ERROR is raised. In all other cases, a run-time descriptor 
check is performed to ensure that the size of each component 
does not exceed 65,535 bytes. If this check fails, then 
CONSTRAINT-ERROR is raised. 


Note that for a one-dimensional array of unsigned 8-bit com¬ 
ponents that is not a VAX Ada string type (see Section 4.2.3 
for a defintion of string types), the descriptor class A can be 
used instead of class SB because the class A descriptor allows 
more than 65,535 components to be represented; in other 
words, class A can be used where it is not known at compile 
time that there will always be fewer than 65,535 components 
for all possible values of the type. 

NCA 

Noncontiguous array: the restrictions on the formal parameter 
type and the descriptor checks that are performed are the 
same as for class A. 


Because VAX Ada never allocates an array of noncontiguous 
components, this descriptor class is only provided for cases in 
which the imported routine requires the NCA descriptor. 


Table 4-4 lists the data types chosen by the compiler for descriptor DTYPE 
fields. Note that for DSC$K_CLASS_A and DSC$K_CLASS_NCA, the 
array component type is used to determine the DTYPE, while for all other 
classes, the formal parameter type is used (that is, the array type is used, 
except when DSC$K__CLASS_S or DSC$IC_CLASS_SB is used to pass 
nonarrays). 
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Table 4-4: Descriptor Data Types Used 


Type Name 

Meaning 

Use 

DSC$K_DTYPE_VU 

Unaligned bit string. 

Always used for parameters 
specified with the class names 
UBS, UBSB, and UBA. Used 
in particular if the formal 
parameter type is a bit string or 
a bit array. 

DSC$K_DTYPE_T 

Character or character string. 

Used if the formal parame¬ 
ter type is any enumeration 
type with a nonnegative rep¬ 
resentation of T'FIRST, with 
a representation of T'LAST 
that is less than 256, and with 
a size of 8 bits. Also used if 
the formal parameter type is a 
string of these enumeration type 
components, which is specified 
with the class name S or SB. 

DSC$K_DTYPE_B 

DSC$K_DTYPE_BU 

DSC$K_DTYPE_W 

DSC$K_DTYPE_WU 

DSC$K_DTYPE_L 

DSC$K_DTYPE_LU 

Byte integer (signed). 

Byte logical (unsigned). 

Word integer (signed). 

Word logical (unsigned). 

Longword integer (signed). 
Longword logical (unsigned). 

Used as appropriate for 8-, 16-, 
or 32-bit components of discrete 
types. 

DSC$K_DTYPE_F 

DSC$K_DTYPE_D 

DSC$K_DTYPE_G 

DSC$K_DTYPE_H 

F_floating. 

D_floating. 

G_floating. 

H_floating. 

Used as appropriate for floating¬ 
point types. 

DSC$K_DTYPE_Z 

Unspecified. 

Used for all other types. 
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Chapter 5 

Calling System Routines 


VAX Ada provides a variety of features for calling VAX/VMS system 

service. Record Management Services (RMS), Run-Time Library, and 

utility routines from an Ada program: 

• The package STARLET provides VAX Ada types, VAX Ada constants 
representing VAX/VMS symbol definitions, and VAX Ada operations 
for calling system and RMS services. The specification of the data 
types is presented in Appendix A; the complete specification of this 
package is in the VAX Ada library of predefined units, and has the file 

specification ADA$PREDEFINED:STARLET_ADC. You can make a 

copy of the specification by typing the ACS command ACS EXTRACT 
SOURCE STARLET (see Developing Ada Programs on VAX/VMS for 
more information on this command). 

• The package SYSTEM provides types and operations for manipulating 
system-related variables and parameters. The specification of this 
package is described in Chapter 13 of the VAX Ada Language Reference 
Manual, and is given in full in Appendix F of that manual. 

• The package CONDITION-HANDLING provides a VAX Ada type 
for VAX/VMS condition values, a set of functions for interpreting 
condition value components, and a set of interface routines for calling 
the Run-Time Library routines LIB$MATCH_COND, LIB$STOP, and 
LIB$SIGNAL. The specification of this package is in Appendix A, as 
well as in the VAX Ada library of predefined units. 

• The VAX Ada import pragmas allow you to write your own VAX 
Ada interface routines in VAX Ada. These pragmas are discussed 
in Chapter 4 and in Chapter 13 of the VAX Ada Language Reference 
Manual. 

• The generic package MATH—LIB (and the predefined VAX Ada in¬ 
stantiations FLOAT_MATH_LIB, LONG—FLOAT—MATH—LIB, and 
LONG—LONG—FLOAT—MATH—LIB) provides interface routines for 
calling many of the Run-Time Library Mathematical Library routines. 
This package and these instantiations are in Appendix A, as well as in 
the VAX Ada library of predefined units. 


Calling System Routines 5-1 



The following sections explain how to call system services and Run¬ 
Time Library routines, and give examples showing the use of the VAX 
Ada features for accomplishing such calls. You should be familiar with 
VAX Ada parameter passing and the VAX Procedure Calling Standard, 
as well as with the VAX Ada import pragmas. Information on these 
topics is given in Chapter 4 of this manual and Chapter 13 of the VAX 
Ada Language Reference Manual. For specific information on the VAX 
Procedure Calling Standard, see the Introduction to System Routines. 

For specific information on VAX/VMS routines themselves, refer to the 
appropriate VAX/VMS documentation: 

• The VAX/VMS System Services Reference Manual provides descriptions 
of all system service routines. 

• The VAX/VMS Record Management Services Reference Manual provides 
descriptions of all RMS routines. 

• The VAX/VMS Run-Time Library Routines Reference Manual provides 
descriptions of all Run-Time Library routines. 

• The VAX/VMS Utility Routines Reference Manual provides descriptions 
of routines that provide a programming interface to various VAX/VMS 
utilities. 


5.1 Writing Calls and Passing Parameters 

When you call a system routine from an Ada program, you must know 
the following information about each parameter: 

• The parameter's data type. 

• The mechanism used to pass the parameter. 

• Whether or not the parameter is optional. 

The description of the routine in the appropriate VAX/VMS documenta¬ 
tion gives this information. You must then interpret the information in the 
call from your Ada program. 

For example, the system service SYSSTRNLNM (Translate Logical Name) 
routine has the following format: 

SYSSTRNLNM [attr],tabnam,lognam[,acmode][.itmlst] 

The description of this service explains that the attr argument represents 
a longword bit mask, the tabnam and lognam arguments represent 
strings, the acmode argument represents a byte, and the itmlst argument 
represents a list of item descriptors. The argument descriptions further 
indicate that the tabnam and lognam arguments are passed by descriptor. 
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and the other arguments are passed by reference. The brackets in the 
format indicate that the attr, acmode, and itmlst arguments are optional. 

To call this service from an Ada program, you can use the routine interface 
provided by the VAX Ada package STARLET (see Section 5.1.1), or you 
can write your own interface by importing the routine with the VAX Ada 
pragma IMPORT_VALUED_PROCEDURE (see Section 5.1.2). 

Table 5-1 lists the Ada equivalents for the VAX data types supported 
by the VAX Procedure Calling Standard and used in system routine and 
Run-Time Library calls. 


Table 5-1: VAX Ada Equivalents for VAX Data Types 


Data Type 

Symbolic Code 

VAX Ada Translation 

Absolute date and time 

DSC$K_DTYPE_ADT 

STARLET.DATE_TIME_TYPE 

Byte integer (signed) 

DSC$K_DTYPE_B 

SHORT_SHORT_INTEGER 

Bound label value 

DSC$K_DTYPE_BLV 

Not available 

Bound procedure value 

DSC$K_DTYPE_BPV 

Not available 

Byte unsigned 

DSC$K_DTYPE_BU 

Any enumerated type whose val¬ 
ues fit into an unsigned byte; 

SYSTEM.UNSIGNED_BYTE 

COBOL intermediate tempo¬ 
rary 

DSC$K_DTYPE_CIT 

Not available 

D_floating 

DSC$K_DTYPE_D 

SYSTEM.D_FLOAT; LONG_FLOAT if 
pragma LONG_FLOAT(D_FLOAT) is in 
effect 

D_floating complex 

DSC$K_DTYPE_DC 

Not available 1 

Descriptor 

DSC$K_DTYPE_DSC 

Not available 1 

F_floating 

DSC$K_DTYPE_F 

FLOAT; SYSTEM.F_FLOAT 

F_floating complex 

DSC$K_DTYPE_FC 

Not available 1 

G_floating 

DSC$K_DTYPE_G 

SYSTEM.G—FLOAT; LONG_FLOAT if 
pragma LONG_FLOAT(G_FLOAT) is in 
effect 

G_floating complex 

DSC$K_DTYPE_GC 

Not available 1 


*Can be simulated in VAX Ada with a record type definition. 
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Table 5-1: (Cont.) VAX Ada Equivalents for VAX Data Types 


Data Type 

Symbolic Code 

VAX Ada Translation 

H_floating 

DSC$K_DTYPE_H 

LONG_LONG_FLOAT; 

SYSTEM.H_FLOAT 

H_floating complex 

DSC$K_DTYPE_HC 

Not available 1 

Longword integer (signed) 

DSC$K_DTYPE_L 

INTEGER 

Longword (unsigned) 

DSC$K_DTYPE_LU 

SYSTEM.UNSIGNED—LONGWORD 

Numeric string, 
left separate sign 

DSC$K_DTYPE_NL 

STRING 

Numeric string, 
left overpunched sign 

DSC$K_DTYPE_NLO 

STRING 

Numeric string, 
right separate sign 

DSC$K_DTYPE_NR 

STRING 

Numeric string, 
right overpunched sign 

DSC$K_DTYPE_NRO 

STRING 

Numeric string, unsigned 

DSC$K_DTYPE_NU 

STRING 

Numeric string, zoned sign 

DSC$K_DTYPE_NZ 

STRING 

Octaword integer (signed) 

DSC$K_DTYPE_0 

Not available 1 

Octaword logical (unsigned) 

DSC$K_DTYPE_OU 

Not available 1 

Packed decimal string 

DSC$K_DTYPE_P 

Not available 1 

Quadword integer (signed) 

DSC$K_DTYPE_Q 

SYSTEM.UNSIGNED-QUADWORD, 
but arithmetic operations not available 

Quadword (unsigned) 

DSC$K_DTYPE_QU 

SYSTEM.UNSIGNED—QUADWORD, 
but arithmetic operations not available 

Character string 

DSC$K_DTYPE_T 

STRING 

Aligned bit string 

DSC$K_DTYPE_V 

Packed BOOLEAN array 

Varying character string 

DSC$K_DTYPE_VT 

Not available 1 

Unaligned bit string 

DSC$K_DTYPE_VU 

Packed BOOLEAN array 

Word integer (signed) 

DSC$K_DTYPE_W 

SHORT_INTEGER 


*Can be simulated in VAX Ada with a record type definition. 
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Table 5-1: (Cont.) VAX Ada Equivalents for VAX Data Types 


Data Type 

Symbolic Code 

VAX Ada Translation 

Word (unsigned) 

DSC$K_DTYPE_WU 

Any enumerated type whose val¬ 
ues fit into an unsigned word; 

SYSTEM.UNSIGNED-WORD 

Unspecified 

DSC$K_DTYPE_Z 

Parameter of any type 

Procedure entry mask 

DSC$K_DTYPE_ZEM 

Not available 

Sequence of instruction 

DSC$K_DTYPE_ZI 

Not available 


5.1.1 Using Package STARLET 

VAX Ada provides the library package STARLET to make system ser¬ 
vice and RMS calls easy and efficient. For instance. Example 5-1 
shows a call to the SYS$TRNLNM system service using the predefined 
STARLET.TRNLNM procedure; the types (documented in Appendix A), as 
well as the procedure interface, are provided by the package. 

Example 5-1: Calling SYS$TRNLNM Using Package 
STARLET 


with SYSTEM; 
with STARLET; 
with CONDITION.HANDLING; 
with TEXT_I0; use TEXT.10; 

with SH0RT_INTEGER_TEXT_I0; use SH0RT_INTEGER_TEXT_I0; 
procedure ORION is 

— Declare short string subtype used in retrieving 
-- translated logical name. 

subtype SHORT.STRING is STRING(1..255); 


(Continued on next page) 
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Example 5-1 (Cont.): Calling SYS$TRIMLNM Using Package 

STARLET 


-- Declare storage for logical name and name size. 

-- Pragma VOLATILE specifies that every read 

— is to the variables in memory, rather than to 
-- a local copy. 

NAME_BUFFER: SHORT.STRING; 

NAME.SIZE : SHORT.INTEGER; 

— Initialized item list. Zeros in the last element 
-- indicate the end of the list. 

ITEM.LIST: STARLET.ITEM_LIST_TYPE(1..2) := 

(1 => (BUF_LEN => NAME.BUFFER'LENGTH, 

ITEM.CODE => STARLET.LNM.STRING, 

BUF_ADDRESS => NAME.BUFFER'ADDRESS, 
RET.ADDRESS => NAME.SIZE'ADDRESS), 

2 => (BUF_LEN => 0, 

ITEM_C0DE => 0, 

BUF_ADDRESS => SYSTEM.ADDRESS_ZERO, 
RET_ADDRESS => SYSTEM.ADDRESS.ZERO)); 

-- Variable for receiving returned condition value. 

RET.STATUS: CONDITION_HANDLING.COND_VALUE_TYPE; 

begin 

-- Call the system service; default values are 

— supplied for ATTR and ACMODE. 

STARLET.TRNLNM(STATUS => RET.STATUS, 

TABNAM => "LNM$SYSTEM", 

LOGNAM => "CYGNUS", 

ITMLST => ITEM.LIST); 


(Continued on next page) 
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Example 5-1 (Cont.): Calling SYS$TRI\ILNM Using Package 

STARLET 


-- Logical test for successful or unsuccessful 
— completion. 

if not CONDITION.HANDLING.SUCCESS(RET.STATUS) 

then 

PUT_LINE("Failed to translate logical name"); 

else 

-- Output values 

PUT("Logical name translates to """); 

PUT(NAME_BUFFER(1 .. INTEGER(NAME.SIZE))); 
PUT_LINE(""""); 

PUTC'Logical name size is ") ; 

PUT(NAME_SIZE); 

NEW_LINE; 
end if; 
end ORION; 


For other system service examples—in particular for examples of handling 
ASTs—see Chapter 7. 


5.1.1.1 Naming Conventions 

The following conventions are used in package STARLET to form names 
for named numbers, system service names, and record components (see 
Section 5.1.1.3 for information on the naming conventions used for record 
types and initialization constants). 

• Because dollar signs () are not legal in Ada identifiers, all dollar 
signs are replaced by underlines. 

• Double underlines are replaced by a single underline. Leading and 
trailing underlines are removed. 

• If the resulting identifier is an Ada reserved word, the last character 
is dropped. This occurs for the system service EXIT, which becomes 
EXI. Other Ada reserved words that are frequently used as record 
component names are ACCESS and TYPE which become ACCES and 
TYP respectively. 
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5.1.1.2 Optional Parameters 

As discussed in Chapter 4, all native-mode VAX languages, VAX/VMS 
system service, RMS, and VAX Run-Time Library routines conform to a set 
of parameter-passing conventions (the VAX Procedure Calling Standard). 
Thus, each time an Ada subprogram or non-Ada routine is called, an 
argument list is passed. The first longword of the argument list contains 
a count of the number of arguments. Each successive longword entry 
represents one parameter, and, depending on the parameter-passing 
mechanism used, can be a 32-bit value, an address of an object, or an 
address of a descriptor. 

Many VAX/VMS and VAX Run-Time Library routines provide the notion 
of an "optional parameter". An optional parameter that is normally passed 
by the reference or descriptor mechanism can be "omitted" by placing a 
zero in the argument list. For example, consider a routine that takes a 
single optional integer parameter, passed by reference. When this routine 
is called, the second longword of the argument list can contain either the 
value zero, to indicate that the parameter is omitted, or it can contain 
the address of a memory location containing an integer value. Observe 
that passing the value zero by reference (placing in the argument list the 
address of a memory location that contains the value zero) is different 
from placing the value zero in the argument list, and is often interpreted 
differently by the called routine. Many Run-Time Library routines and 
RMS routines allow optional parameters to be indicated by shortened 
argument lists. However, most VAX/VMS system services require a fixed 
number of arguments. That is, a value of zero must be placed in the 
argument list to indicate that a particular parameter has been omitted. 

Ada provides the notion of a "default parameter expression". That is, a 
parameter (specifically only a parameter of mode in) can be omitted in a 
call and a default parameter value is automatically supplied. (The default 
parameter expression is evaluated each time the subprogram is called, so 
it is not feasible for the subprogram body to provide the default value if it 
is not present—the default value must be provided as an actual parameter 
on each and every call.) 

The VAX/VMS optional-parameter and the Ada default-parameter notions 
are not equivalent. VAX/VMS and the Run-Time Library routines permit 
the equivalent of optional in out or out parameters, whereas Ada allows 
only in parameters to have default expressions. Further, placing a zero 
in a VAX/VMS argument list to omit an argument can have a different 
interpretation from a zero passed by reference or a null string passed by 
descriptor. 
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In all STARLET interface routines (except the RMS routines), a default 
expression using the VAX Ada NULL_PARAMETER attribute is used 
for optional in parameters passed by reference or descriptor. If you 
omit a parameter association for one such optional formal parameter, a 
zero is placed in the argument list, regardless of the parameter-passing 
mechanism normally used for the argument. 

The SYS$ASSIGN service routine in the following example from the pack¬ 
age STARLET has two optional parameters, ACMODE and MBXNAM. 
Since the parameter mechanism specified for ACMODE is VALUE, a 
default value of zero is used. The parameter-passing mechanism speci¬ 
fied for MBXNAM is DESCRIPTOR. MBXNAM is of subtype DEVICE— 
NAME-TYPE, which is a subtype of STRING. A default expression of 
DEVICE—NAME—TYPE'NULL—PARAMETER is used to indicate that the 
value zero is to be placed in the argument list if this parameter is not 
specified on a call. 

-- $ASSIGN 


Assign I/O Channel 


$ASSIGN devnam , chan , [acmode] ,[mbxnam] 


devnam = address of device name or logical name 
string descriptor 

chan = address of word to receive channel number 
assigned 

acmode = access mode associated with channel 
mbxnam = address of mailbox logical name string 

descriptor, if mailbox associated with device 


procedure 

ASSIGN ( 

STATUS 

: Out 

COND_VALUE_TYPE; — return value 

DEVNAM 

: in 

DEVICE_NAME_TYPE; 

CHAN 

: out 

CHANNEL_TYPE; 

ACMODE 

: in 

ACCESS_MODE_TYPE := 

ACCESS_MODE_ZERO; — 0 value 

MBXNAM 

: in 

DEVICE_NAME_TYPE : = 

DEVICE_NAME_TYPE•NULL.PARAMETER); 


pragma INTERFACE (EXTERNAL, ASSIGN); 

pragma IMPORT_VALUED_PROCEDURE (ASSIGN, "SYS$ASSIGN", 
(COND_VALUE_TYPE, DEVICE_NAME_TYPE, CHANNEL_TYPE, 
ACCESS_MODE_TYPE, DEVICE_NAME_TYPE), 

(VALUE, DESCRIPTOR(S), REFERENCE, 

VALUE, DESCRIPTOR(S))); 
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Overloading is used for optional in out or out parameters (since a default 
expression cannot be specified). Two Ada procedure declarations are 
given in STARLET for each such parameter. (The IMPORT_VALUED_ 
PROCEDURE pragma is then used to map both Ada subprograms to the 
same VAX/VMS system service.) The first declaration specifies the type 
to be used if an argument is to be passed to the system service. In the 
second, the optional parameter is an in parameter of type ADDRESS and 
has a default expression of ADDRESS—ZERO. Because the parameter is 
to be passed by value, the argument can be omitted entirely in the call if 
named association is used. (If the call uses positional association, either 
ADDRESS_ZERO or ADDRESS'NULL—PARAMETER must be specified.) 

For VAX/VMS services with multiple in out or out parameters, overload¬ 
ings are provided for all combinations, except where two parameters are 
closely related (for example, a string descriptor is used to hold an output 
string and the related parameter is set to the string length). 

In the following example from package STARLET, the parameter VALBLK 
is an in out parameter passed by reference, and therefore cannot have 
a default value. The second signature is provided to allow the VALBLK 
parameter to be omitted in a call to SYS$DEQ. 

-- $DEQ 


Dequeue Lock 

$DEQ [lkid] ,[valblk] ,[acmode] , [flags] 
lkid = lock ID of the lock to be dequeued 
valblk = address of the lock value block 
acmode = access mode of the locks to be dequeued 
flags = optional flags 

LCK$M_DEQALL 


procedure DEQ ( 

STATUS : out COND_VALUE_TYPE; 

LKID : in LOCK_ID_TYPE 

VALBLK : in out LOCK_VALUE_BLOCK_TYPE; 

ACMODE : in ACCESS_MODE_TYPE 

FLAGS : in UNSIGNED.LONGWORD 


return value 
LOCK_ID_ZERO; 

ACCESS_MODE_ZERO; 
0 ) ; 
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procedure DEQ ( 


STATUS 

LKID 

: out 
: in 

COND_VALUE_TYPE; 
LOCK_ID_TYPE 

-- return value 
:= LOCK_ID_ZERO; 

-- To omit optional VALBLK argument 


VALBLK 

: in 

ADDRESS 

:= ADDRESS_ZERO; 

ACMODE 

FLAGS 

: in 
: in 

ACCESS_MODE_TYPE 

UNSIGNED.LONGWORD 

:= ACCESS_MODE_ZERO 
: = 0) ; 


pragma INTERFACE (EXTERNAL, DEQ); 

pragma IMPORT_VALUED_PROCEDURE (DEQ, "SYS$DEQ", 

(COND_VALUE_TYPE, LOCK_ID_TYPE, LOCK_VALUE_BLOCK_TYPE, 
ACCESS_MODE_TYPE, UNSIGNED.LONGWORD), 

(VALUE, VALUE, REFERENCE, VALUE, VALUE)); 

pragma IMPORT_VALUED_PROCEDURE (DEQ, "SYS$DEQ", 
(COND_VALUE_TYPE, LOCK_ID_TYPE, ADDRESS, 
ACCESS_MODE_TYPE, UNSIGNED_LONGWORD), 

(VALUE, VALUE, VALUE, VALUE, VALUE)); 


RMS routines allow AST error and/or success handlers to be specified. 
Since RMS does not require a fixed number of arguments and since the 
optional arguments appear at the end of the argument list, overloading is 
used in STARLET to indicate that the handler arguments are optional. 

For example, the interface specification for the RMS WRITE routine from 
package STARLET is as follows: 


— $WRITE 

Write Block to File 

$WRITE rab, [err], [sue] 
rab = address of rab 

err = address of user error completion routine 
sue = address of user success completion routine 
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procedure WRITE ( 

STATUS : out COND_VALUE_TYPE; -- return value 

RAB : in out RAB.TYPE; 

ERR : in AST.HANDLER; 

SUC : in AST.HANDLER); 

procedure WRITE ( 

STATUS : out COND_VALUE_TYPE; -- return value 

RAB : in out RAB.TYPE); 

pragma INTERFACE (EXTERNAL, WRITE); 

pragma IMPORT.VALUED.PROCEDURE (WRITE, "SYS$WRITE", 

(COND_VALUE_TYPE, RAB_TYPE, AST_HANDLER, AST.HANDLER), 

(VALUE, REFERENCE, VALUE, VALUE)); 

pragma IMPORT.VALUED.PROCEDURE (WRITE, "SYS$WRITE", 
(COND.VALUE.TYPE, RAB_TYPE), 

(VALUE, REFERENCE)); 

In summary, when calling system and RMS services with optional param¬ 
eters from package STARLET, you should 

• Look at the system or RMS services manual and determine which 
parameters you want to specify in the call and which you want to 
omit. 

• Look in STARLET at the first signature (if overloaded) to determine 
the parameter types. Look in STARLET or in Appendix A for the 
declarations of these parameter types. 

• Make the call using named association, giving only arguments you 
want to pass. The use of named association is highly recommended. 


5.1.1.3 STARLET Record Type Declarations 

STARLET contains record type declarations for VAX/VMS control blocks, 
including the control blocks used by RMS routines: the file access block 
(FAB), record access block (RAB), extended attribute block (XAB), and 
name block (NAM). 

Many VAX/VMS control blocks have a multilevel structure. You can 
represent this structure in VAX Ada by defining a record type for each 
nested structure. For example, the following record declaration shows a 
portion of the record type defined in STARLET for the FOP (file-processing 
options) field of a FAB (RMS file access block). (See the VAX/VMS Record 
Management Services Reference Manual for a description of the individual 
options.) The name of the type begins with "FAB—" to indicate that FAB- 
FOP—TYPE is a type declared for a component of a record of type FAB- 
TYPE. 
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type FAB_FOP_TYPE is 

record 


FILLER.l : 

BOOLEAN 

MXV 

BOOLEAN 

DLT 

BOOLEAN 

FILLER.3 

BOOLEAN 

ESC 

BOOLEAN; 

TEF 

BOOLEAN; 

OFP 

BOOLEAN; 

KFO 

BOOLEAN; 

FILLER_4 

BOOLEAN; 


end record; 

FAB_TYPE is declared in STARLET as a record type that contains a 
component called FOP whose type is FAB_FOP_TYPE: 

type FAB.TYPE is 

record 

BID: UNSIGNED JBYTE; 

BLN: UNSIGNED JBYTE; 

FOP: FAB_FOP_TYPE; 


end record; 

The following example illustrates how the FOP component can be ac¬ 
cessed: 


with STARLET; 

procedure MODIFY.FOP (FAB1 : STARLET.FAB.TYPE, 

FAB2 : STARLET.FAB_TYPE) is 


begin 


— Set the file processing options of FAB1 to 
-- those of FAB2. 


FAB1.FOP := FAB2.FOP; 


-- Set the DLT option to indicate that the file 
-- associated with FAB2 will be deleted when closed. 

FAB2.F0P.DLT := TRUE; 

end; 
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An initialization constant is also provided for each record type defined in 
STARLET to facilitate the initialization of objects of the type. The name 
of the constant is formed by appending "_INIT" to the type name. For 
example, the following is a portion of the STARLET initialization constant 
for the type FAB_TYPE: 

FAB_TYPE_INIT : constant FAB.TYPE := 

(BID => FAB_C_BID, 

BLN => FAB_C_BLN, 

FOP => (FILLER.l => FALSE, 

MXV => FALSE, 

DLT => FALSE, 

. . . ), 

. . . ); 

A typical use might be 

declare 


— Initialize FAB to 


contain standard FAB defaults. 


FAB : STARLET.FAB_TYPE := STARLET.FAB_TYPE_INIT; 
STATUS : CONDITIONHANDLING.COND_VALUE_TYPE; 

begin 

STARLET.OPEN (STATUS, FAB); 


end; 

Likewise, FAB_FOP_TYPE_INIT is defined in STARLET as a constant 
that can be used to initialize an object or component of type FAB_FOP_ 
TYPE. A portion of the definition in STARLET is as follows: 

FAB_FOP_TYPE_INIT : constant FAB_FOP_TYPE := 


(FILLER_1 

=> 

FALSE, 

MXV 

=> 

FALSE, 

DLT 

=> 

FALSE, 

FILLER.3 

=> 

FALSE, 

ESC 

=> 

FALSE, 

TEF 

=> 

FALSE, 

OFP 

=> 

FALSE, 

KFO 

=> 

FALSE, 

FILLER_4 

=> 

FALSE) 
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Note that the component names used in this example for the FAB_FOP_ 
TYPE include several that begin with "FILLER—". These are reserved 
fields that are currently unused, but that might be used in the future. 

The number of reserved fields in any particular record declaration is 
likely to change from one VAX/VMS release to another. Further, the 
names assigned to the reserved fields are also likely to change. For 
example, if the component called "FILLER—3" were to be used in a new 
VAX/VMS release, the name of the "FILLER—4" component would change 
to "FILLER—3" and "FILLER—4" would no longer exist. Thus, you should 

never explicitly refer to a component that begins with the text "FILLER_" 

in your program. The initialization constants in STARLET, in this case 
FAB—FOP—TYPE—INIT, should be used to initialize such components. 

For example, to initialize a variable of type FAB_FOP_TYPE, you would 
write 

FOP : FAB_FOP_TYPE := FAB_FOP_TYPE_INIT; 

FAB—FOP—TYPE—INIT can also be used to initialize the FOP component 
of a FAB. For example: 

procedure MOD.FOP (FAB : STARLET.FAB.TYPE) is 

begin 

FAB.FOP := FAB_FOP_TYPE_INIT; 

end; 

Example 5-2 shows the use of some of the RMS control blocks declared in 
package STARLET. The example is a program that maps a file to the first 
available space using the system service SYS$CRMPSC (Create and Map 
Section), and the RMS routine SYSSOPEN. 


Calling System Routines 


5-15 




Example 5-2: Calling SYS$CRMPSC Using Package 
STARLET 


with SYSTEM; use SYSTEM; 
with STARLET; 
with CONDITION_HANDLING; 
with TEXT.IO; use TEXT.IO; 
procedure MAP_FILE is 

NAME : constant := "map.file.ada"; 

START.LOC, END.LOC : ADDRESS; 

FAB : STARLET.FAB.TYPE := STARLET.FAB_TYPE_INIT; 
XAB : STARLET.XAB_TYPE(XAB_C_FHC) 

:= STARLET.XABFHC.INIT; 
pragma VOLATILE(FAB); 
pragma VOLATILE(XAB); 

STATUS : CONDITION.HANDLING.COND.VALUE.TYPE; 

CHANNEL : STARLET.CHANNEL.TYPE; 

RETADR, 

INADR : STARLET.ADDRESS_RANGE_TYPE; 

begin 

START.LOC := ADDRESS.ZERO; 

END.LOC := ADDRESS.ZERO; 

— First, open the file 

FAB.FNA := NAME'ADDRESS; 

FAB.FNS := NAME'LENGTH; 

FAB.FOP.UFO := TRUE; 

FAB.XAB := XAB'ADDRESS; 

STARLET.OPEN(STATUS, FAB); 


(Continued on next page) 
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Example 5-2 (Cont.): Calling SYS$CRMPSC Using Package 

STARLET 


-- Check for the file's existence 

— and, if it exists, that its 

— format is ok 

if CONDITION.HANDLING.SEVERITY(STATUS) /= STS_K_SUCCESS 

then 

PUT_LINE("Can't find file"); 

else 

if (FAB.ORG /= STARLET.FAB_C_SEQ) or else 
(not FAB.RAT.CR) or else 
(FAB.RFM /= STARLET.FAB_C_VAR) 

then 

PUT_LINE("File in wrong format"); 

else 

CHANNEL := STARLET.CHANNEL.TYPE(FAB.STV); 

-- Now, map it to the first 
— available space 

INADR(O) := ADDRESS_ZERO; 

INADR(l) := ADDRESS.ZERO; 

STARLET.CRMPSC(STATUS => STATUS, 

INADR => INADR, 

RETADR => RETADR, 

FLAGS => STARLET.SEC_M_EXPREG, 
CHAN => CHANNEL); 


(Continued on next page) 
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Example 5-2 (Cont.): Calling SYS$CRMPSC Using Package 

STARLET 


-- check to see if mapping worked; 

-- if it did, calculate its starting 
-- and ending points 

if not CONDITION.HANDLING.SUCCESS(STATUS) 

then 

PUT_LINE("CRMPSC failed"); 

else 

START.LOC := RETADR(O); 
if XAB.FFB /= 0 

then 

END.LOC := RETADR(O) + INTEGER(XAB.EBK-1)*512 
+ INTEGER(XAB.FFB); 

else 

END.LOC := RETADR(O) + INTEGER(XAB.EBK)*512; 

end if; 
end if; 
end if; 
end if; 
end; 


5.1.1.4 Passing Ada Subprograms as Parameters 

Some system routines take as arguments the addresses of other routines or 
subprograms (for example, SYS$PUTMSG). To pass an Ada subprogram 
as a parameter to a system routine, the subprogram must be exported (see 
the discussion of export pragmas in Chapter 4). An exported subprogram 
must be a library unit or must be declared in the outermost declarative 
part of a library package. You can then pass the subprogram's address to 
the system routine with the Ada ADDRESS attribute. 

If you attempt to pass the address of a subprogram that is not exported, 
the compiler issues a warning message. 
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5.1.2 Using the IMPORT_VALUED_PROCEDURE Pragma 


If you need to write your own routine interface (for example, you want 
to write a specialized interface, or the routine you are calling is not in 
STARLET), you can use the pragma IMPORT_VALUED_PROCEDURE to 
import the routine. (All of the interface routines in STARLET involve the 
use of this pragma.) 

Pragma IMPORT_VALUED_PROCEDURE is specially designed for 
calling system routines. That is, system routines return status values 
using the same parameter-passing mechanisms as Ada uses for returning 
function results. However, many system routines also cause side effects 
on their parameters; and Ada functions, by definition, have only in 
parameters, which cannot be modified by the function. Pragma IMPORT— 
VALUED-PROCEDURE allows an imported routine to be interpreted as 
a procedure in an Ada program and as a function in the external system 
environment. 

When you use the IMPORT-VALUED—PROCEDURE pragma, the first 
parameter of the imported "procedure" must be an out parameter passed 
by value. The value is returned as any function value is returned (in 
general registers RO and Rl, depending on its size). The other parameters 
can be specified with the modes in, in out, or out, according to the 
actions of the service routine parameters. See Chapter 4 of this manual 
and Chapter 13 of the VAX Ada Language Reference Manual for more 
information about using this pragma. 

Example 5-3 shows the use of the IMPORT—VALUED—PROCEDURE 
pragma to call the SYS$TRNLNM system service. In contrast to Example 
5-1, which also calls the SYS$TRNLNM service, this example does not 
depend on package STARLET. 
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Example 5-3: Calling SYS$TRNLNM Using an Import Pragma 


with SYSTEM; 

with CONDITION.HANDLING; 
with TEXT.IO; use TEXT.IO; 

with SHORT_INTEGER_TEXT_IO; use SHORT_INTEGER_TEXT_IO; 
procedure ORION is 

-- Declare short string subtype used in retrieving 
-- translated logical name. 

subtype SHORT.STRING is STRING(1..255); 

-- Declare storage for logical name and name size. 
-- Pragma VOLATILE specifies that every read 
-- of the variables must be to memory, rather 
— than to a local copy. 

NAME.BUFFER: SHORT.STRING; 

NAME.SIZE : SHORT.INTEGER; 

-- Declare subtypes for SYS$TRNLNM parameters. 

subtype LOGICAL_NAME_TYPE is STRING; 

subtype ACCESS_MODE_TYPE is SYSTEM.UNSIGNED.WORD; 

— Define the VAX/VMS item list type. 

type ITEM_REC_TYPE is 

record 

BUF.LEN : SYSTEM.UNSIGNED.WORD; 

ITEM.CODE : SYSTEM.UNSIGNED.WORD; 

BUFJVDDRESS: SYSTEM.ADDRESS; 

RET.ADDRESS: SYSTEM.ADDRESS; 

end record; 

type ITEM.LIST.TYPE is 

array (NATURAL range <>) of ITEM_REC_TYPE; 

-- Declare constant representing an item code to 
-- be specified in the item list. 

LNM.STRING : constant := 2; 


(Continued on next page) 
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Example 5-3 (Cont.): Calling SYS$TRNLNM Using an Import 

Pragma 


-- Initialized item list. Zeros in the last element 
-- indicate the end of the list. 

ITEM_LIST: ITEM_LIST_TYPE(1..2) := 

(1 => (BUF_LEN => NAME.BUFFER'LENGTH, 

ITEM_C0DE => LNM_STRING, 

BUF_ADDRESS => NAME.BUFFER'ADDRESS, 
RET.ADDRESS => NAME_SIZE'ADDRESS), 

2 => (BUF.LEN => 0, 

ITEM.CODE => 0, 

BUF_ADDRESS => SYSTEM.ADDRESS.ZERO, 
RET_ADDRESS => SYSTEM.ADDRESS_ZER0)); 

-- Variable for receiving returned condition value. 

RET.STATUS: CONDITION.HANDLING.COND_VALUE_TYPE; 

-- Specify the Ada procedure that corresponds to the 
-- system service. 

procedure TRNLNM ( 


STATUS: 

out 

CONDITION_HANDLING.COND_VALUE_TYPE; 

ATTR 

in 

SYSTEM.UNSIGNED.LONGWORD := 

SYSTEM.UNSIGNED_LONGWORD'NULL.PARAMETER; 

TABNAM: 

in 

LOGICAL_NAME_TYPE; 

LOGNAM: 

in 

LOGICAL_NAME_TYPE; 

ACMODE: 

in 

ACCESS_MODE_TYPE := 

ACCESS_MODE_TYPE'NULL_PARAMETER; 

ITMLST: 

in 

ITEM_LIST_TYPE := 

ITEM_LIST_TYPE'NULL_PARAMETER); 


(Continued on next page) 
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Example 5-3 (Cent.): Calling SYS$TRNLNM Using an Import 

Pragma 


-- Use pragmas INTERFACE and IMPORT_VALUED_PROCEDURE to 
-- set up the interface to the actual system service. 

-- Note specification of parameter-passing mechanisms 
-- by means of the IMPORT_VALUED_PROCEDURE pragma. 

pragma INTERFACE (SYSSERV, TRNLNM); 
pragma IMPORT_VALUED_PROCEDURE ( 

INTERNAL => TRNLNM, 

EXTERNAL => "SYS$TRNLNM M , 

PARAMETER.TYPES => 

(CONDITION.HANDLING.COND_VALUE_TYPE, 

SYSTEM.UNSIGNED_LONGWORD, 

LOGICAL_NAME_TYPE, 

LOGICAL_NAME_TYPE, 

ACCESS_MODE_TYPE, 

ITEM_LIST_TYPE), 

MECHANISM => 

(VALUE, 

REFERENCE, 

DESCRIPTOR(S) , 

DESCRIPTOR(S) , 

REFERENCE, 

REFERENCE)); 


begin 

— Call the system service; default values are 
— supplied for ATTR and ACMODE. 

TRNLNM(STATUS => RET.STATUS, 

TABNAM => "LNMSSYSTEM", 

LOGNAM => "CYGNUS", 

ITMLST => ITEMJLIST); 


(Continued on next page) 
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Example 5-3 (Cont.): Calling SYS$TRINILNM Using an Import 

Pragma 


-- Logical test for successful or unsuccessful 
-- completion. 

if not CONDITION.HANDLING.SUCCESS(RET.STATUS) 

then 

PUT_LINE("Failed to translate logical name"); 

else 

-- Output values 

PUTC'Logical name translates to """); 

PUT(NAME_BUFFER(1 .. INTEGER(NAME.SIZE))); 
PUT_LINE("""") ; 

PUT("Logical name size is "); 

PUT(NAME_SIZE); 

NEW.LINE; 
end if; 
end ORION; 


5.2 Testing Return Condition Values 

Many VAX/VMS system service, RMS, and Run-Time Library routines 
return a numeric status value that indicates whether or not they success¬ 
fully completed the requested operation. The first parameter of all system 
service and RMS routines declared in package STARLET is an out param¬ 
eter, which is set to a status value when the routine finishes execution. 
This parameter is of type COND_VALUE_TYPE, which is declared in the 
predefined package CONDITION-HANDLING. 

When a system status value is returned, you can test for success or failure 
by using one of the condition value evaluation functions provided in 
package CONDITION—HANDLING. You can also compare it to one of 
the severity codes declared in package STARLET, or you can compare it 
to one of the specific condition values that the service returns. You can 
make the latter comparison by using one of the interface routines for the 
Run-Time Library routine LIB$MATCH_COND, which are also provided 
in package CONDITION-HANDLING. 
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For example, the program ORION in Example 5-1 uses the CONDITION- 
HANDLING function SUCCESS to test for successful logical name trans¬ 
lation: 

procedure ORION is 
RET.STATUS: COND_VALUE_TYPE; 

begin 

TRNLNM(STATUS => RET.STATUS, 

TABNAM => "LNM$SYSTEM", 

LOGNAM => "CYGNUS", 

ITMLST => ITEM_LIST); 

if not CONDITION.HANDLING.SUCCESS(RET.STATUS) then 
-- raise an error 

else 

-- get the name and size and print them out 

end if; 

end; 

Alternatively, you can compare the severity of the status value with one 
of the following constants (defined in package STARLET): 

STS_K_WARNING 

STS_K_SUCCESS 

STS_K_ERROR 

STS_K_INFO 

STS_K_SEVERE 

\ 

For example: 


procedure ORION is 
RET.STATUS: COND_VALUE_TYPE; 

begin 

TRNLNM(STATUS => RET_STATUS, 

TABNAM => "LNMSSYSTEM", 

LOGNAM => "CYGNUS", 

ITMLST => ITEM.LIST); 

if CONDITION_HANDLING.SEVERITY(RET.STATUS) /= STS_K_SUCCESS then 
-- raise an error 

else 

-- get the name and size and print them out 

end if; 

end; 
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Finally, you can use the CONDITION-HANDLING.MATCH—COND 
function to test the return status for other condition values (also defined in 
package STARLET): 

with SYSTEM; use SYSTEM; 
with STARLET; use STARLET; 

with CONDITION_HANDLING; use CONDITION.HANDLING; 

procedure ORION is 

RET.STATUS: COND_VALUE_TYPE; 

MATCH.VALUE: INTEGER; 

ERROR: exception; 

begin 

TRNLNM(STATUS => RET.STATUS, 

TABNAM => "LNM$SYSTEM", 

LOGNAM => "CYGNUS", 

ITMLST => ITEM_LIST); 

if not CONDITION.HANDLING.SUCCESS(RET.STATUS) 

then 

-- find out what went wrong; condition value 
— codes are given in module $SSDEF in STARLET 

MATCH.VALUE := CONDITION.HANDLING.MATCH.COND ( 

RET.STATUS, 

SS.IVLOGTAB, 

SS.NOLOGNAM); 

-- raise an error exception 
raise ERROR; 
else 

-- print out the name and size 

end if; 

exception 

when ERROR => 

PUT_LINE("Failed to translate logical name"); 
case MATCH.VALUE is 

when 1 => PUT.LINE("TABNAM is not a" & 

"logical name table"); 

when 2 => PUT_LINE("Logical name is not in" & 

"the name table"); 

when others => null; 
end case; 

end; 

To look at the various condition value components, you can use the set of 
functions provided by package CONDITION—HANDLING (see 
Appendix A). 
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5.3 Calling Asynchronous System Services 


Some system services can be executed either synchronously or asyn¬ 
chronously. A synchronous service causes your program to wait while 
the service request is being processed. An asynchronous service queues 
a request and returns control to your program while the request is be¬ 
ing processed. When the request is satisfied, the system service uses 
an asynchronous system trap (AST) to interrupt program execution and 
transfer control to a user-specified procedure. Examples of asynchronous 
services are SYS$GETJPI and SYS$QIO; their synchronous forms are 
SYS$GETJPIW and SYS$QIOW. The VAX/VMS System Services Reference 
Manual describes these system services in more detail. 

You can call asynchronous system services from a VAX Ada program 
by using tasks and the VAX Ada predefined AST_ENTRY pragma and 
attribute. The use of tasks is described and the rules for using the AST— 
ENTRY pragma and attribute are given in Chapter 9 of the VAX Ada 
Language Reference Manual and in Chapter 7 of this manual. Chapter 7 
also gives several examples of programs where ASTs are handled. 

Chapter 7 also describes the package TASKING—SERVICES, which 
provides interface routines for calling services that involve AST parameters 
(SYS$QIO, SYS$GETJPI, and so on) from tasks. Note that the subprogam 
specifications in package TASKING—SERVICES have Ada bodies, and thus 
the NULL—PARAMETER attribute cannot be used for optional parameters 
(see Section 5.1.1.1). As a result, multiple overloadings are used for each 
combination of optional parameters in the same manner as is done for 
system services that have optional in out or out parameters. 


5.4 Calling Mathematical Routines 

VAX Ada predefines the generic library package MATH—LIB, which pro¬ 
vides interface functions for many of the Run-Time Library mathematical 
routines and declares exceptions that can be raised. Instantiated versions 
of this package for types FLOAT, LONG—FLOAT, and LONG—LONG- 
FLOAT are also provided for convenience. 

For example, you could use the predefined instantiation FLOAT—MATH- 
LIB as follows: 
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with FLOAT_MATH_LIB; use FLOAT_MATH_LIB; 
procedure TRIG_FUNCTIONS is 

X. Y : FLOAT := 3.0; 

begin 

— Test sine-cosine identity 

Y := COS(X)**2 + SIN(X)**2; 

-- Find hyperbolic sine two ways 

Y := SINH(X); 

Y := EXP(X) - EXP(-X))/2.0; 

-- Find hyperbolic arc sine 

Y ;= L0G(X + (SQRT(X**2 + 1.0))); 

end; 

If you had declared your own floating-point type, you could declare your 
own package to instantiate MATH_LIB, and then write a similar procedure 
as follows: 

with MATH.LIB; 
package MY.FLOATING is 

type MY_FL0ATING_TYPE is digits 6; 
package MY_FLOATING_MATH_LIB is 
new MATH_LIB(MY_FLOATING_TYPE); 
end MY_FLOATING; 

with MY.FLOATING; use MY_FLOATING; 
procedure TRIG.FUNCTIONS is 
use MY_FLOATING_MATH_LIB; 

X, Y : FLOAT := 3.0; 
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begin 


-- Test sine-cosine identity 

Y := COS(X)**2 + SIN(X)**2; 

— Find hyperbolic sine two ways 

Y := SINH(X); 

Y := EXP(X) - EXP(-X))/2.0; 

— Find hyperbolic arc sine 

Y := L0G(X + (SQRT(X**2 + 1.0))); 
end TRIG_FUNCTIONS; 

See Chapter 8 for more information on predefined instantiations. 
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Chapter 6 

Exception Handling 


VAX Ada exception handling, as defined in Chapter 11 of the VAX Ada 
Language Reference Manual , is implemented using the routines and related 
VAX/VMS system services that comprise the VAX Condition Handling 
Facility (CHF). However, VAX Ada exception handling is implemented 
so that you do not need to call CHF routines and services directly. This 
chapter outlines how VAX Ada exception handling is related to VAX 
condition handling, and explains how to do exception handling in an Ada 
program that calls or is called from the external environment. 

Ada exception handling and the rules for using the VAX Ada pragmas to 
import and export exceptions are covered fully in Chapters 11 and 13 of 
the VAX Ada Language Reference Manual. The CHF is described fully in 
the VAX/VMS Run-Time Library Routines Reference Manual. You should be 
familiar with the material in these two manuals before trying to use the 
information in this chapter. 


6.1 Relationship Between Ada Exception Handling and VAX 
Condition Handling 

All VAX Ada exceptions are encoded as VAX condition values: each 
predefined exception is encoded as a unique 32-bit condition value; each 
user-defined exception is encoded either as a unique 32-bit condition 
value or as the general VAX Ada condition value denoted by the name 
ADA$_EXCEPTION plus a signal argument that is the address of the 
exception name. Section 6.1.1 lists the predefined exceptions and explains 
the encoding and naming of exceptions in more detail. 

Once defined, an exception may be raised. Raising generally causes the 
CHF procedure LIB$STOP to be called, and the exception's condition 
value to be passed as one of the signal arguments. A vector of signal 
arguments and a vector of mechanism arguments are built, and a search 
is then made for an exception handler. The same sequence of events also 
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occurs if a signaled VAX condition is propagated to an Ada program from 
the external environment. 

In VAX Ada, a general condition handler is automatically established for 
all stack frames that have exception handlers, and a run-time table of 
active exception parts is maintained for each frame. (Because blocks do 
not have their own stack frames, this condition handler is established for 
the subprogram, package body, or task body that contains one or more 
blocks with exception handlers.) The general condition handler determines 
which specific Ada exception handler eventually gains control, the stack is 
unwound to that specific handler, and execution continues from there. 

If no handler is found, and the exception propagates as far as it can 
go—to the level of a task or a main program—a VAX/VMS or VAX 
Ada run-time catch-all handler gains control. In the case of a task, the 
VAX Ada catch-all handler terminates execution of the task (without 
generating a message); other tasks continue executing, as required by the 
Ada language. In the case of a main program, any tasks declared in library 
packages are allowed to terminate, and the exception is propagated to one 
of the VAX/VMS-defined default handlers (traceback, catch-all, or last- 
chance). The default handler terminates execution and generates an error 
message, which is sent to the output files denoted by the logical names 
SYS$OUTPUT and SYS$ERROR (see Chapter 2 for more information 
on how these names are interpreted). The VAX/VMS Run-Time Library 
Routines Reference Manual gives more information about VAX/VMS default 
handlers. 

In the case of the VAX Ada predefined exception CONSTRAINT— 
ERROR, the events are a bit different. To reduce code size, sometimes 
a DIGITAL-reserved instruction code (FFFF) is generated (rather than a 
call to LIB$STOP) to indicate the occurrence of a compiler-detected con¬ 
straint violation. (See Table 6-4 in Section 6.1.4 for a list of the constraint 
checks that are made.) When such an instruction is executed, a reserved 
opcode fault (SS$_OPCDEC) is raised by the VAX/VMS operating system. 
The VAX Ada general condition handler then immediately converts each 
SS$_OPCDEC fault to CONSTRAINT-ERROR, and the search for an 
exception handler is made (a matching condition value is sought, and so 
on). Because of this immediate conversion, SS$_OPCDEC faults are never 
propagated if they are signaled in Ada subprograms. Note, however, 
that if an SS$OPCDEC fault is signaled from a non-Ada routine, it is not 
converted. 

This implementation of CONSTRAINT—ERROR is generally invisible to 
your program. However, if a constraint error results in a reserved opcode 
fault, and you are using the VAX/VMS Symbolic Debugger to observe the 
raising of exceptions, the debugger will report the error as SS$_OPCDEC 
instead of as CONSTRAINT—ERROR. See the Developing Ada Programs on 
VAX/VMS for more information. 
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If you explicitly raise CONSTRAINT-ERROR from your Ada program, 
reserved instructions are not generated; LIB$STOP is called as previously 
described. 

Table 6-1 summarizes the VAX Ada implementation of exception han¬ 
dling. 


Table 6-1: Relationship Between Ada Exception Handling 
and the CHF 


Ada Exception Handling 

CHF Implementation 

Enter an Ada frame with an exception 

Establish the general VAX Ada 

part . 1 

condition handler for the sur¬ 
rounding stack frame; if the 
general handler is already estab¬ 
lished, maintain information about 
currently active exception parts 
with a pointer to an internal VAX 
Ada run-time table. 

Raise an exception. 

Signal a condition with a call to 
LIB$STOP . 2 

Invoke an exception handler. 

Unwind ($UNWIND) to the stack 
frame of the Ada frame containing 
the exception part, and to the 

PC at the start of the appropriate 
exception handler. 

Re-raise the same exception. 

Call LIB$STOP with a copy of 
the signal arguments that caused 
invocation of the currently active 
exception part. Note that the 
SS$_RESIGNAL feature of the 
CHF is not used to re-raise an 
exception. 


^The term Ada frame refers to a frame, as defined by the Ada language: a block statement or the 
body of a subprogram, package, task unit, or generic unit. The term stack frame (synonymous with 
the term call frame) refers to a run-time VAX structure that stores information about a subprogram, 
package, task, or instantiated generic unit, and includes information about any contained blocks. 

2 

A DIGIT AL-reserved instruction may be used to implement the raising of any compiler-generated 
constraint errors. See the discussion of CONSTRAINT-ERROR in Section 6.1. 
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Table 6-1: (Cont.) Relationship Between Ada Exception 
Handling and the CHF 


Ada Exception Handling CHF Implementation 

Raise an Ada format exception. 3 Call LIB$STOP with the condition 

value ADA$_EXCEPTION and 
one signal argument. The signal 
argument is the address of a 
counted ASCII string (ASCIC 
string) that is the text of the name 
of the exception. 

Raise a VMS format exception. 3 Call LIB$STOP with a unique 

32-bit VAX condition value. 


Exceptions with an Ada format are any user-defined exceptions declared without import-export 
pragmas, or any user-defined exceptions declared with import-export pragmas that specify a value of 
ADA for the pragma FORM parameter. Exceptions with VMS format are any predefined exceptions or 
any user-defined exceptions declared with import-export pragmas that specify a value of VMS for the 
pragma FORM parameter. See Sections 6.1.1, 6.2.1, and 6.2.2. 


In particular, note from Table 6-1 that the raising of an exception in an 
Ada program involves either the CHF routine LIB$STOP or the generation 
of a DIGITAL-reserved instruction that causes a reserved operand fault. 
These actions implement the Ada language requirement that the occur¬ 
rence of an exception must terminate the current Ada frame and transfer 
control to an exception handler. The effect is that once an exception is 
raised in an Ada program, control cannot return to the point at which the 
exception occurred: execution is noncontinuable. See Section 6.2.3 for a 
discussion of the consequences. 

In some cases, the exception's signal argument vector may be copied 
before control is transferred to a handler. For example, if the handler re¬ 
raises the exception, the signal argument vector must be copied so that the 
same signal arguments can be used to raise the exception again. A copy is 
also needed when an exception is raised at the point of a task rendezvous 
(the language requires that the exception be propagated to both the called 
and the calling task). Section 6.1.2 describes how signal argument copying 
is done, and outlines some side effects. 
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6.1.1 Naming and Encoding Ada Exceptions 


VAX Ada provides predefined exceptions in the packages STANDARD, 
IO—EXCEPTIONS, AUX_IO_EXCEPTIONS, and SYSTEM. Each prede¬ 
fined exception is encoded with a VMS format : a unique 32-bit VAX con¬ 
dition value with a symbolic name. The predefined VAX Ada exceptions 
have symbolic names of the form 

ADA$_exception_name 

Thus, for example, the exception NUMERIC-ERROR (from the package 
STANDARD) has the symbolic name ADA$_NUMERIC—ERROR, and the 
exception DATA—ERROR (from the package IO—EXCEPTIONS) has the 
symbolic name ADA$_DATA—ERROR. 

The predefined exceptions are listed in Table 6-2; the situations in which 
they are raised are described in the VAX Ada Language Reference Manual. 


Table 6-2: Ada Predefined Exceptions 


Package STANDARD 

Package IO-EXCEPTIONS 

CONSTRAINT-ERROR 

STATUS-ERROR 

NUMERIC-ERROR 

MODE-ERROR 

PROGRAM-ERROR 

NAME-ERROR 

STORAGE-ERROR 

USE-ERROR 

TASKING-ERROR 

DEVICE-ERROR 


END-ERROR 


DATA-ERROR 


LAYOUT-ERROR 

Package SYSTEM 

Package AUX_IO_EXCEPTIONS 

NON_ADA_ERROR 

LOCK-ERROR 


EXISTENCE-ERROR 


KEY-ERROR 


Ada also allows you to declare your own exceptions so that you can 
anticipate and handle more specific errors than those covered by the 
predefined exceptions. For example: 

INVALID.INPUT : exception; 

Once declared, the exception name INVALID—INPUT can be used in a 
raise statement and as an exception choice in an Ada frame. 
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In general, such user-defined exceptions are encoded with an Ada format : 
they all have the same general 32-bit VAX condition value with the 
symbolic name ADA$_EXCEPTION, plus an additional signal argument 
that makes each value unique. This signal argument is the address (32-bit) 
of the counted ASCII string (ASCIC string) that represents the name of the 
exception. (The first byte of the string contains the number of characters 
in the exception name; the remaining bytes contain the characters of the 
exception name.) The string address is assigned at link time and can 
change each time the program is linked. 

You can cause user-defined exceptions to be encoded with a VMS format 
by using either of the pragmas IMPORT-EXCEPTION and EXPORT- 
EXCEPTION. See Section 6.2 for details. 


6.1.2 Copying Exception Signal Arguments 

An exception's signal argument vector is copied if the exception is re¬ 
raised by its handler or if it is raised at the point of a task rendezvous. 
This copying is done so that essentially the same signal arguments are 
used when the exception is propagated. 

When a signal argument vector is copied, it is marked as such by being 
chained to one of two special VAX Ada-specific primary condition values: 
ADA$_EXCCOP, which indicates that the copy is complete, or 
ADA$_EXCCOPLOS, which indicates that the original signal has been 
modified and some information may have been lost. The chaining causes 
ADA$_EXCCOP or ADA$_EXCCOPLOS to become the primary condi¬ 
tion in the signal argument vector. The condition that originally caused 
the exception to be raised then becomes the second condition value in the 
signal argument vector. 

The only cases in which information may be lost from the signal argument 
vector during copying are when the exception is imported, when it is not 
a predefined or user-defined Ada exception, and when it does not match a 
hardware or RMS condition. In such cases, the vector may have a signal 
argument that points to a stack area that must be unwound to reach the 
handler. When copying occurs, such signal arguments are zeroed. 

Whether or not information has been lost by copying, the handling of 
the exception in Ada is not affected. The handling of the exception in 
non-Ada code is affected only if messages that depend on zeroed FAO 
(Formatted ASCII Output) arguments are involved; such messages are 
printed with embedded FAO directives. 
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6.1.3 Matching Ada Exceptions and System-Defined VAX Conditions 


In VAX Ada, the matching of exceptions to exception choices depends on 
the matching of the condition values assigned to the exception and the 
choice names. In particular, two user-defined, Ada format exceptions— 
exceptions encoded as ADA$_EXCEPTION plus an ASCIC string—match 
only if the addresses of their ASCIC strings match. If the raised exception 
is an imported VAX condition (see Section 6.2.1), it matches an exception 
choice only if the name in the exception choice matches the internal name 
of the imported VAX condition. Imported VAX conditions also match 
the exception choice others (see Section 6.2.4) and the exception name 
SYSTEM.NON__ADA_ERROR (see Section 6.2.5). 

Some VAX conditions are treated as being equivalent to certain Ada pre¬ 
defined exceptions. When one of these conditions is signaled during the 
execution of an Ada program, the effect is as if the predefined exception 
were raised, and the condition can be caught by an Ada exception handler 
that exists to catch the predefined exception. Table 6-3 lists the VAX 
conditions that have Ada predefined equivalents. 

Table 6-3: VAX Conditions that Match Ada Exceptions 


Condition Name 

Meaning 

Exception Name 

SS$_INTDIV 

Integer divide by zero trap 

NUMERIC-ERROR 

SS$_FLTDIV 

Floating/decimal divide by zero trap 

NUMERIC-ERROR 

SS$_FLTDIV_F 

Floating divide by zero fault 

NUMERIC-ERROR 

SS$_INTOVF 

Integer overflow trap 

NUMERIC-ERROR 

SS$_FLTOVF 

Floating overflow trap 

NUMERIC-ERROR 

SS$_FLTOVF_F 

Floating overflow fault 

NUMERIC-ERROR 


Note that these VAX conditions are not converted to NUMERIC-ERROR. 
If one of them is signaled and propagates out of a main program, the 
result is an informational message identifying the event as a NUMERIC- 
ERROR (that is, you could have caught it with a NUMERIC—ERROR 
handler), as well as the error message and traceback associated with the 
actual condition. 
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6.1.4 Suppressing Checks 


In accordance with the language definition, VAX Ada provides a set of 
run-time checks that underlie the predefined exceptions. The VAX Ada 
Language Reference Manual explains each check that the compiler performs 
and gives the corresponding exceptions that can arise. For convenience, 
this correspondence is summarized in Table 6-4. 


Table 6-4: Run-Time Checks and Their Corresponding 
Predefined Exceptions 


Check 

Predefined 

Exception Raised 

ACCESS-CHECK 

DISCRIMINANT-CHECK 

INDEX-CHECK 

LENGTH-CHECK 

RANGE-CHECK 

CONSTRAINT-ERROR 

DIVISION-CHECK 

OVERFLOW-CHECK 

NUMERIC-ERROR 

ELABORATION-CHECK 

PROGRAM-ERROR 

STORAGE-CHECK 

STORAGE-ERROR 


To suppress checks, you can use the SUPPRESS—ALL pragma (see the 
VAX Ada Language Reference Manual) or the /NOCHECK qualifier on the 
ADA and ACS COMPILE and RECOMPILE commands (see Developing 
Ada Programs on VAX/VMS). 

The presence of a SUPPRESS—ALL pragma or the use of /NOCHECK 
qualifiers does not guarantee that exceptions will not be raised. For 
example, certain checks are not suppressed in VAX Ada. These checks 
are the hardware checks DIVISION-CHECK and OVERFLOW-CHECK 
(for floating-point types), where the hardware catches the error and 
passes control directly to the operating system. STORAGE—CHECK is 
also not suppressed (except for stack checks). Thus, an exception may 
be propagated from a called unit in which the corresponding check was 
suppressed; NUMERIC—ERROR is propagated from subunit B to MAIN- 
EXCEPTIONS in Example 6-1. 
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Example 6-1: Use of Pragma SUPPRESS—ALL 


with TEXT.IO; use TEXT.IO; 

with INTEGER TEXT 10; use INTEGER TEXT 10; 


procedure MAIN is 

procedure A is 
begin 

end; 

procedure B is separate; 


procedure C is separate; 


begin 

B; 

exception 

when NUMERIC.ERROR => 
PUT_LINE("Division by 
end MAIN; 


separate (MAIN) 
procedure B is 

A: INTEGER := 1; 
I: INTEGER := 0; 
begin 

A := A/I; 

PUT(A); 

end; 

pragma SUPPRESS_ALL; 


-- checks are not 
-- suppressed in A 


-- checks are 
-- suppressed in B 

-- checks are not 
-- suppressed in C 

-- exception B 
-- propagated to here 

zero -- propagated up!"); 


— DIVISION.CHECK 
-- raised, even though 
-- SUPPRESS.ALL is 
-- specified 

-- pragma must follow 
-- unit to which 
-- it applies 


separate (MAIN) 
procedure C is 
begin 

end; 
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You should also be aware that when you suppress checks, your program 
may become erroneous. For example, if you suppress checks in a library 
unit or subunit that contains a number of arrays, you will suppress 
INDEX-CHECK, but array processing will continue, whether or not you 
exceed the specified ranges. The results of that unit or subunit will be 
unpredictable. 

Therefore, in general, you should use the SUPPRESS—ALL pragma or 
/NOCHECK qualifiers only to improve the run-time performance of your 
program, not to eliminate the raising of exceptions. 


6.2 Mixed-Language Exception Handling 

VAX Ada provides the pragmas IMPORT—EXCEPTION and EXPORT- 
EXCEPTION for use in a mixed-language programming environment. 
IMPORT—EXCEPTION allows you to import an exception declared in a 
non-Ada program and handle it within your Ada program. EXPORT- 
EXCEPTION allows you to export an Ada exception so that it can be 
treated as a VAX condition. 

The following sections explain the use of these pragmas. 


6.2.1 Importing Exceptions 

The pragma IMPORT—EXCEPTION associates an Ada exception name 
with either a VAX condition value or another Ada exception name—both 
external to your program—and then allows you to use that name in your 
Ada program. The full syntax and usage rules for this pragma are given 
in Chapter 13 of the VAX Ada Language Reference Manual. The syntax is 
summarized here for convenience: 

pragma IMPORT.EXCEPTION 

(internal_name [, external_designator] 

[, [ FORM => ] { ADA I VMS > 

[, [ CODE => ] static_integer_expression ]); 

With the IMPORT—EXCEPTION pragma, you can associate an Ada 
exception name with either a numeric condition value or a global symbol 
that denotes a VAX condition: the CODE parameter represents a numeric 
condition value, and the external designator represents a global symbol. 
You can determine the format of the exception with the FORM parameter 
(see Section 6.1.1 for definitions of Ada and VMS formats; the format for 
imported exceptions is VMS by default). An imported exception can be 
raised by a raise statement and caught by an Ada exception handler that 
names the exception. 
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You can give a VAX condition value to an Ada exception by first defining 
a condition with the VAX Message Utility (see the VAX/VMS Utilities 
Reference Volume), and then using IMPORT-EXCEPTION to associate the 
Ada exception name with the VAX condition. 

In the next example, the procedure QUADRATIC—FORMULA com¬ 
putes and prints the real roots of a quadratic equation. It illustrates 
the importing of the VAX condition MTH$_SQUROONEG, which 
can be raised by the routine; the IMPORT—EXCEPTION pragma asso¬ 
ciates the exception name SQRT_NEGATIVE with the VAX condition 
MTH$_SQUROONEG. If the call to the SQRT function in the proce¬ 
dure QUADRATIC—FORMULA attempts to compute the square root of 
a negative number, the exception SQRT_NEGATIVE is raised. Control 
is transferred to the exception handler, which completes execution of the 
procedure by printing a message. 


with FL0AT_TEXT_I0; use FLOAT_TEXT_IO; 
with FLOAT_MATH_LIB; use FLOAT_MATH_LIB; 

-- these packages are predefined by VAX Ada 
-- for convenience 
with TEXT.IO; use TEXT_I0; 
procedure QUADRATIC_F0RMULA is 


A, B, C, D : FLOAT; 
SQRT.NEGATIVE : exception; 
pragma IMPORT.EXCEPTION ( 
SQRT_NEGATIVE, 

"MTH$_SQUR00NEG"); -- 


internal_name 
external_designator 
by default use 
VMS format 


begin 

GET(A); GET (B); GET(C); 

D := SQRT(B**2 - 4.0*A*C);-- exception will be 

-- raised here if 
-- B**2 - 4.0*A*C 
-- is negative 

PUT("Real Roots : XI = "); 

PUT( (-B - D)/(2.0*A)); 

PUT(" X2 = "); 

PUT((-B + D)/(2.0*A)); 

exception 

when SQRT.NEGATIVE => 

PUT_LINE("Imaginary Roots."); 
end QUADRATIC.FORMULA; 
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The next example is a declaration that shows how you could import 
the VAX condition SS$_ACCVIO using its numeric code. Note that no 
external symbol is referenced in this case (it is illegal if the code option 
is specified). Also note that the format is VMS by default (the required 
format for importing VMS conditions). 


SS.ACCVIO : exception; 
pragma IMPORT.EXCEPTION ( 

SS.ACCVIO, — internal_name 

CODE => 16#0C#); -- numeric condition value 

Finally, the declaration 


NEW.VMS : exception; 
pragma IMPORT.EXCEPTION 
NEW.VMS, 

"SOME_NAME", 

FORM => VMS); 


( 

internal_name 

external_designator of a condition 
defined with the VAX Message Utility 
explicitly specify VMS format 


shows how you can import a VAX/VMS condition that has been created 
previously with the VAX Message Utility. 


6.2.2 Exporting Exceptions 

The EXPORT-EXCEPTION pragma associates an Ada exception with 
either a VAX condition value or another Ada exception name, and then 
allows you to use that name in the external environment. The full syntax 
and usage rules for this pragma are given in Chapter 13 of the VAX 
Ada Language Reference Manual . The syntax is summarized here for 
convenience: 

pragma EXPORT_EXCEPTION 

(internal_name [, external_designator] 

[, [ FORM => ] { ADA | VMS > 

[, [ CODE => ] integer_literal_expression ]); 

If you export a VMS format exception (see Section 6.1.1) to a non-Ada 
routine, that routine can treat it as an ordinary VAX condition. In other 
words, the routine can process the exception using its own condition¬ 
handling mechanisms (for example, with ON units if the routine is written 
in PL/I, or with LIB$ESTABLISH if the routine is written in FORTRAN). 

If you export an Ada format exception (see Section 6.1.1), the external 
designator becomes a global symbol, which is the address of the excep¬ 
tion's ASCIC string name. Because an exception with the Ada format is 
unique only in the address of its ASCIC string, any non-Ada routine to 
which such an exception is exported must examine the exception's signal 
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arguments in order to determine a match. Similarly, any non-Ada routine 
to which an Ada format exception is propagated must determine if the 
primary condition is ADA$_EXCEPTION, and, if so, must examine the ex¬ 
ception's first FAO signal argument to determine if the argument matches 
the value of the external designator. 

The following examples show how to declare Ada and VMS format 
exceptions, so that they can be exported to the external environment: 


ADA.ERROR : exception; 
pragma EXPORT.EXCEPTION 
(ADA.ERROR, 
"MY_PACKAGE_ADA", 

FORM => ADA); 

VMS.ERROR : exception; 
pragma EXPORT.EXCEPTION 
(VMS.ERROR, 

"MY_PACKAGE_ADA", 

FORM => VMS, 

CODE => 16#8018004#); 


-- internal_name 
-- external_designator 
-- Ada format 


-- internal_name 
-- external_designator 
-- VMS format 

— VAX/VMS condition value 


6.2.3 Noncontinuable Execution 

A significant effect of VAX Ada exception handling is that an Ada excep¬ 
tion is never continuable from the point at which the exception is raised. 
In other words, if a VAX condition is signaled and the code for an Ada 
exception part is executed in response to the condition, the condition is 
always treated as a noncontinuable Ada exception. 

The consequences of this rule are as follows: 

• If a VAX condition is signaled from the external environment and 
propagated to an Ada frame with dependent tasks, the signal becomes 
noncontinuable. 

• An Ada subprogram that does not contain any exception handlers 
(which name the raised exception) is transparent to the CHF when a 
VAX condition is signaled in a mixed-language context. 

For example, if a FORTRAN program Pl_FOR calls an Ada program 

P2_ADA, and P2_ADA calls another FORTRAN program P3_FOR, 

P3_FOR could signal a condition, Pl_FOR could handle the signal and 

continue the execution of P3_FOR, and P2_ADA would be unaffected. 

From the Ada subprogram's point of view, the signal would never 
have happened. 
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• The Ada when others clause matches all Ada exceptions and almost 
all VAX conditions, imported or not. The effect of using this clause, 
therefore, is to convert any raised or propagated VAX condition into a 
noncontinuable exception. In the preceding example, 
if P2_ADA contained a when others clause, PLFOR would not 
be able to continue the execution of P3_FOR. (Section 6.2.4 gives 
more information on the use of this clause, and gives an extensive 
example of its effect.) (Note that the few VAX conditions that are part 
of the mechanism of implementing VAX Ada are not caught by others 
clauses.) 


This rule also affects the use of certain VAX Run-Time Library fault 
handlers in a program that calls Ada subprograms (see Section 6.2.6). 


6.2.4 The Exception Choice Others 

You can use the exception choice others in the last exception handler of a 
frame to catch all exceptions not listed in previous handlers of the frame. 
This choice also catches all VAX conditions except 

SS$_DEBUG 
SS$_UNWIND 

These two VAX conditions are used to implement the VAX Ada run-time 
environment, and are never caught by an Ada exception handler. Even 
if you import one of these conditions and name it in an Ada exception 
handler, the handler is never invoked to respond to the condition. 

The exception choice others is particularly useful for performing opera¬ 
tions and then re-raising exceptions that you did not anticipate and for 
which you did not write specific handlers. For example: 

begin 

-- sequence of statements for a block 

exception 

when SINGULAR | NUMERIC_ERROR => 

PUT (" MATRIX IS SINGULAR "); 

when others => 

-- perform some cleanup operations 

raise; 

end; 

Here, if an exception other than SINGULAR or NUMERIC-ERROR is 
raised, the when others handler gains control, and the exception will be 
re-raised in the containing frame. 
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If you are doing mixed-language programming, you should keep in mind 
that if a VAX condition is propagated to an Ada frame that contains an 
others handler or a when clause that names a matching exception, the 
signal will become noncontinuable (see Section 6.2.3). 

For example, suppose you have a working FORTRAN program, called 
Pl—FOR, for which you have enabled underflow conditions at compile 
time (see the VAX FORTRAN User's Guide). A default FORTRAN handler 
(FOR$UNDERFLOW_HANDLER) is then established at the level of the 
main program to process any underflow conditions that arise. That is, if an 
operation in the program underflows and the condition is not processed 
by another handler, FOR$UNDERFLOW_HANDLER assumes control. 
This handler keeps a count of the number of underflow conditions and 
continues execution from the point of the signal. 

Pl—FOR calls several routines, including a FORTRAN subroutine named 
P2_FOR. Figure 6-1 illustrates the call frames for these routines; the 
circled numbers indicate the order of execution. If an underflow condition 
is signaled in P2_FOR, FOR$UNDERFLOW_HANDLER gains control, 
processes the condition, and continues execution of P2—FOR. 

Figure 6-1: Execution of a FORTRAN Program with 
FOR$UNDERFLOW—HANDLER 


FOR$UNDERFLOW_HANDLER 


PROGRAM PI_FOR O 

CALL P2_FOR 

END 


SUBROUTINE P2_FOR © 

© 

X A*B - 

next statement © 

END 


underflow 

signaled 


o 
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Now suppose that when enhancing the program, you insert a call to 
an Ada procedure called P3_ADA. In this case, Pl—FOR calls P3_ADA, 
which contains an exception handler with the exception choice others, and 
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which calls P2_FOR. Figure 6-2 illustrates the calling sequence for this 
series of routines. If P2_FOR signals underflow, the handler in P3_ADA 
gains control and converts the condition to a noncontinuable exception. 

Figure 6-2: The Effect of an Ada Procedure Containing an Others Handler 


FOR$UNDERFLOW_HANDLER 


PROGRAM PI_FOR Q 

EXTERNAL P3^ADA 


CALL P3_ADA 

© 

END 


procedure P3_ADA is © 

pragma IMPORT__PROCEDURE (P2_FOR); 

P2_FOR; © 

exception 

when others=> © 
end; 


o 

SUBROUTINE P2_FOR 

X - A • B _ underflow 

next statement signa ed 

END 
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If the handler in P3_ADA does not re-raise the exception, execution 
resumes in Pl_FOR at the statement after the call to P3—ADA. 

P2_FOR does not continue executing, which was the original intent. If 
the Ada handler re-raises the exception, the exception is propagated to 
FOR$UNDERFLOW_HANDLER. When FOR$UNDERFLOW_HANDLER 
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attempts to continue from a noncontinuable exception, the result is a fatal 
error and execution terminates. 

Thus, when programming in more than one language, you should use 
the exception choice others carefully. For each subprogram you should 
anticipate the errors that can occur, and you should explicitly name each 
possible error in an exception handler. In addition, you should understand 
the behavior of a subprogram (and the main program) if you are adding it 
to an existing application. 

Furthermore, you should avoid establishing global error handlers at the 
level of a main program. For example, rather than using a compile¬ 
time switch to generally establish FOR$UNDERFLOW_HANDLER in a 
FORTRAN program, you can use VAX Run-Time Library calls to explicitly 
establish in certain places. Figure 6-3 illustrates a repaired version of 
the FORTRAN program, which instead establishes FOR$UNDERFLOW_ 
FiANDLER for the subroutine P2_FOR. Then, when underflow is signaled 
in P2—FOR, the handler gains control, processes the condition, and 
continues execution of P2_FOR. The signal is never propagated to the 
Ada procedure P3—ADA. 
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Figure 6-3: FOR$UNDERFLOW-HANDLER Established for a 
FORTRAN Subroutine 


PROGRAM PI_FOR O 

EXTERNAL P3_^ADA 

CALL P3_ADA 

END 


procedure P3_ADA is © 

pragma IMPORT_PROCEDURE (P2_FOR); 

P2_FOR; © 

exception 

when others- 

end; 


FOR$UNDERFLOW_HANDLER 

l-1 • 


SUBROUTINE P2_F0R © 

EXTERNAL FOR$UNDERFLOW_HANDLER 

CALL LIB$ESTABLISH (FOR$UNDERFLOW_HANDLER) 

© 

X A * P ^_ underflow ^ 

next statement © signaled ^ 

END 
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6.2.5 The Exception Choice NON—ADA—ERROR 


To allow you to treat non-Ada conditions as a special subclass of Ada 

exceptions, VAX Ada provides the exception choice NON_ADA_ERROR 

in the package SYSTEM. NON_ADA_ERROR matches itself and any VAX 

condition whose facility field is not ADA. It is encoded as a predefined 
exception with the unique condition value ADA$_NON_ADA_ERROR. 

NON_ADA_ERROR also matches Ada exceptions for which the pragma 
IMPORT-EXCEPTION or EXPORT-EXCEPTION is given and for which 
the VMS format has been specified. 


6.2.6 Fault Handlers 

Fault handlers are usually established as catch-all stack handlers, or 
they are called from condition handlers (such as the VAX Run-Time 
Library routine LIB$DECODE_FAULT), and need the signal information 
generated at the time the fault occurred in order to execute properly. 
Because VAX Ada exception handling involves unwinding of the stack 
frame to the start of the handler, signal information is lost when an 
exception is handled in Ada (the saved signal arguments described in 
Section 6.1.2 are accessible only to the Ada run-time library and not to the 
underlying CHF routines). Thus, you cannot 

• Establish a fault handler in Ada. 

• Call a VAX Run-Time Library fault handler from an Ada exception 
part (even if the handler is imported with the IMPORT—PROCEDURE 
pragma or using package STARLET). 

• Catch a fault in an Ada program when that program has called a 
procedure in another language, and then continue from the point of 
the fault. 


The only way to set up a fault handler in Ada is to use the VAX/VMS 
vectored exception mechanism. That is, you must call the system ser¬ 
vice SYS$SETEXV to assign the address of a fault handler to the primary 
or secondary exception vector (see Chapter 5 of this manual for infor¬ 
mation on how to call system services, and the VAX/VMS Run-Time 
Library Routines Reference Manual for an explanation of exception vectors). 
Because the CHF looks for a handler in the primary and secondary excep¬ 
tion vectors before it looks for a handler in an Ada frame, the vectored 
fault handler gains control before the search for an Ada handler can be¬ 
gin. The fault handler then processes the fault, and the fault is dismissed 
before it can ever be propagated to an Ada handler. 
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6.3 Exceptions and Tasking 


Exception handling in VAX Ada interacts with tasking in several ways. 

First, as required by the Ada language, the propagation of an exception 
from an Ada frame must await the termination of all tasks that depend 
on that frame. If a dependent task never terminates, then the exception is 
never propagated. You can avoid this situation 

• By having the exception handler call an entry in the task that causes 
the task to terminate. 

• By making sure that the task will eventually reach a select statement 
with an open terminate alternative. 

• By using an abort statement. (The use of abort is not recommended ex¬ 
cept as a last resort. See Section 7.4.3 for a more complete discussion.) 

You can use the VAX/VMS Symbolic Debugger to diagnose situations in 
which an exception may wait forever for a dependent task; see Developing 
Ada Programs on VAX/VMS. 

Second, VAX Ada requires that tasks declared in a library package or 
defined by an access type declared in a library package must terminate 
before execution is returned to the VAX/VMS DCL command interpreter. 
This additional VAX Ada requirement means that such tasks are guar¬ 
anteed to always reach one of the language-defined points at which task 
termination can occur. A consequence of this rule is that propagation of 
an exception out of the frame of the main program does not occur until all 
tasks declared in library packages terminate. After all such tasks have ter¬ 
minated, the exception is propagated to a VAX/VMS default handler (see 
Section 6.1). In cases where such a task fails to terminate, you can use the 
VAX/VMS Symbolic Debugger to diagnose the problem (see Developing 
Ada Programs on VAX/VMS). 

Third, the Ada language requires that exceptions propagating from an 
accept statement propagate in the calling task as well as in the called task. 
To implement this requirement, VAX Ada copies the signal arguments 
from the called task to the calling task. This copy operation is identical 
to the copying that occurs when an exception is going to be re-raised (see 
Section 6.1.2). In particular, the copied exception has a different primary 
condition, either ADA$_EXCCOP or ADA$_EXCCOPLOS, and some 
information in the signal arguments may have been lost (zeroed). 
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Chapter 7 

Tasking 


Ada tasks are entities that execute in parallel. Thus, for example, you can 
use tasks to take data concurrently from several sources, you can use them 
to do terminal input-output and a series of calculations at the same time, 
or you can use them to call asynchronous VAX/VMS system services. 

This chapter provides information on how to use VAX Ada tasks ef¬ 
fectively, giving, in particular, information on how to use tasks in the 
VAX/VMS environment: 

• Section 7.1 introduces tasking on VAX/VMS, defining terms and 
presenting tasking concepts. 

• Section 7.2 describes how task storage is allocated, explains how you 
can control that allocation, and discusses the possibility of task stack 
overflow in a mixed-language environment. 

• Section 7.3 describes how control is switched from one task to an¬ 
other and how you can affect the response time and fairness of task 
switching. 

• Section 7.4 treats programming considerations that you should be 
aware of when you use VAX Ada tasks: deadlock, busy waiting in a 
mixed-language environment, use of abort statements, the effects of 
interrupting program execution with CTRL/Y, shared variables, and 
reentrancy. 

• Section 7.5 discusses the calling of VAX/VMS system routines from 
VAX Ada tasks, and characterizes the VAX Ada package TASKING— 
SERVICES. 

• Section 7.6 describes a mechanism for handling VAX/VMS asyn¬ 
chronous system traps (ASTs). 

• Section 7.7 discusses ways to measure tasking performance and tune 
that performance. 


Tasking 7-1 




If you are not familiar with Ada tasking, you should read Chapter 9 of 
the VAX Ada Language Reference Manual before reading this chapter. For 
information on any VAX/VMS concepts presented in this chapter, see the 
VAX/VMS System Services Reference Manual and the VAX/VMS Run-Time 
Library Routines Reference Manual. 


7.1 Introduction to Using Ada Tasks on VAX/VMS 

A task is entity whose execution proceeds in parallel with the execution of 
other tasks. The Ada language allows you to declare both task types and 
task objects. 

A special kind of task—an environment task —is automatically created 
when you run a main VAX Ada program. This task—the main task —first 
elaborates any library packages associated with the program, and then 
calls the main program (see Chapter 10 of the VAX Ada Language Reference 
Manual). When execution of the main program is completed, and all tasks 
that depend on its library packages terminate, the main task is deleted, 
and control returns to the VAX/VMS operating system. 

Any task is said to depend on a number of masters. The kinds of entities 
that can be the masters of a task are: blocks, tasks, subprograms, or library 
packages. If you declare a task object in a block, for example, the block 
is the master of the created task, and the task depends on the block. If 
the block is executed within the statement part of a subprogram, then 
that subprogram is another master of the task and the task depends on 
it too. An immediate master is the master that immediately contains the 
declaration of a task object, or that immediately contains the definition of 
the access type whose designated type is a task type. A key rule is that 
control cannot leave a master until all its dependent tasks have terminated. 
(If some dependent task chooses not to terminate, none of its masters can 
exit, and the program, or a portion of it, appears to "hang"). 

Each time you create a task (for example, by declaring a task object, or 
evaluating an allocator that points to a task object), VAX Ada automat¬ 
ically creates a task control block to manage the task. When the task is 
activated, VAX Ada creates a stack for the statements which the task will 
execute, and allows the task to vie for the processor on which your process 
is executing. 

Because all tasks in any Ada program (including the main task) run 
in the context of a single process, control can switch from one task to 
another very quickly. This switch can occur at any of the several machine 
instructions that make up an Ada program statement; that is, the switch 
can occur midway through the execution of an Ada source line. Because of 
task switching, you will often need to synchronize the execution of tasks 
in your program to get the behavior you desire. Synchronization involves 
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making sure that the right things happen in the right order. The usual 
means of synchronizing tasks is to use Ada's rendezvous mechanism. 

Example 7-1 is an example of using tasks to do input-output and another 
activity in parallel. The example program reads in an array of integers, 
and sorts them using a quick sort. The sorting is done by one task, 
and another task (running in parallel) allows you to see how the sort is 
progressing by executing input-output statements while the sort is being 
done. The comments in the example point out various tasking concepts 
(activation, synchronization, and so on). These concepts are defined fully 
in the VAX Ada Language Reference Manual. 

Example 7-1: Interactive Array Sort Using Tasks 


-- Example showing that one task can execute while another 
-- waits for input-output. 

-- This program has a background task that sorts an array while 
-- another task interacts with the terminal user. The interactive 
-- task, upon user command, will display the array at any time 
-- during the sort. 

— Before running this program, you must make sure that the input 
-- file is not a process-permanent file (SYS$INPUT) otherwise, 

— the lower priority sorting task will not run. To avoid 
-- using SYS$INPUT, first type the following: 

-- $ define ADA$INPUT TT 

-- Program to sort an array via quicksort and examine it 

— as it is sorted. 


(Continued on next page) 
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Example 7-1 (Cont.): Interactive Array Sort Using Tasks 


with TEXT_I0; use TEXT.IO; 
with INTEGER_TEXT_IO; use INTEGER_TEXT_IO; 
with FLOAT.TEXT.IO; use FLOAT.TEXT.IO; 
procedure TASKSORT is 

-- Enable time slicing 
pragma TIME_SLICE(0.3); 

type QUICKARRAY is array (INTEGER range <>) of INTEGER; 
-- Array to be sorted and shared among tasks 

A : QUICKARRAY(1..120); 

ASIZE : INTEGER; 

— Force array references to be made to actual 
— array storage (rather than to a copy) 

pragma VOLATILE(A); 

SENTINEL : STRING(1..120) := (1..120 => ' '); 

— Task to synchronize access to the array being sorted 

task GRANTOR is 

entry GRAB.ACCESS; 
entry RELEASE.ACCESS; 
end GRANTOR; 

-- Lower priority "background task" to do sorting 
task QUICK is 

entry QSORT (ARG.I, ARG.J: INTEGER); 
pragma PRIORITY(3); 
end QUICK; 


(Continued on next page) 
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Example 7-1 (Cont.): Interactive Array Sort Using Tasks 


-- Higher priority "interactive task" to display 
-- sort results 

task USER is 

pragma PRIORITY(7); 
end USER; 

task body GRANTOR is 
begin 
loop 

select 

accept GRAB_ACCESS; 
accept RELEASE.ACCESS; 

or 

terminate; 
end select; 
end loop; 

end GRANTOR; 

task body QUICK is 

I, J, MIDDLE.KEY : INTEGER; 

KEY.INDEX : INTEGER; 

KEY : INTEGER; 

function FIND.MIDDLE (I,J: INTEGER) return INTEGER is 
FIRST : INTEGER; 

KEY : INTEGER; 

begin 

FIRST := A(I); 
for KEY in (1+1) .. J loop 
if A(KEY) > FIRST then 
return KEY; 

elsif A(KEY) < FIRST then 
return I; 
end if; 
end loop; 
return 0; 
end FIND.MIDDLE; 


(Continued on next page) 
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Example 7-1 (Cont.): Interactive Array Sort Using Tasks 


function DIVIDE.ARRAY (I,J : INTEGER; 

MIDDLE.KEY : INTEGER) 

return INTEGER is 

LEFT, RIGHT, TEMP : INTEGER; 

begin 

— Rendezvous to synchronize access to the 
-- array for partitioning 

GRANTOR.GRAB.ACCESS; 

LEFT := I; 

RIGHT := J; 

loop 

TEMP := A(LEFT); 

A(LEFT) := A(RIGHT); 

A(RIGHT) := TEMP; 

while A(LEFT) < MIDDLE.KEY 

loop 

LEFT := LEFT + 1; 

end loop; 

while A(RIGHT) >= MIDDLE.KEY 

loop 

RIGHT := RIGHT - 1; 

end loop; 

exit when LEFT > RIGHT; 

end loop; 

-- Rendezvous to synchronize end of 
-- array access 

GRANTOR.RELEASE.ACCESS; 

PUT.LINE("Partial sort complete"); 
return LEFT; 
end DIVIDE.ARRAY; 


(Continued on next page) 
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Example 7-1 (Cont.): Interactive Array Sort Using Tasks 


procedure QUICKSORT (I,J: INTEGER) is 

begin 

KEY_INDEX := FIND_MIDDLE(I,J); 
if KEY_INDEX /= 0 then 
delay 8.0; 

MIDDLE_KEY := A(KEY_INDEX); 

KEY := DIVIDE_ARRAY(I,J,MIDDLE.KEY); 
QUICKSORT (I, KEY-1) ; 

QUICKSORT (KEY, J) ; 

end if; 

end QUICKSORT; 

begin 

select 

accept QSORT (ARG_I,ARG_J: INTEGER) do 
I := ARG_I; 

J := ARG_J; 
end QSORT; 

or 

terminate; 
end select; 

PUT_LINE("The sorting task has started"); 
QUICKSORT (I, J) ; 

PUT_LINE("The sorting task has completed"); 
end QUICK; 

procedure PRINT_ARRAY is 
begin 


— Again, use GRANTOR task rendezvous to 
-- synchronize array access for printing 

GRANTOR.GRAB_ACCESS; 
for I in 1..ASIZE 

loop 

PUT(A(I),WIDTH=>3); 

end loop; 

NEW.LINE; 

GRANTOR.RELEASE.ACCESS; 
end PRINT.ARRAY; 


(Continued on next page) 
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Example 7-1 (Cont ): Interactive Array Sort Using Tasks 


task body USER is 
I : INTEGER; 

LAST : NATURAL; 

begin 

PUT_LINE("Type in the number of" & 

"integers you want sorted,"); 
PUT_LINE("and then type a <RET>."); 

GET(ASIZE); 

PUT_LINE("Now, type in a string of integers," & 
"separated by spaces, "); 
PUT_LINE("that you want sorted. End the" & 
"string with a <RET>."); 
for I in 1..ASIZE 
loop 

GET(A(I)) ; 

end loop; 

PUT("The initial array is "); 

PRINT.ARRAY; 

-- Start the sorting task 


QUICK.QS0RT(1,ASIZE); 


-- Allow the terminal user to see the array at any time 


loop 

PUT_LINE("Type: <RET> to see partially" & 
"sorted array or e to exit"); 

GET.LINE(SENTINEL, LAST); 

if LAST >= 1 and then (SENTINEL (1) = 'E 1 or 

SENTINEL (1) = • e') then 

exit; 
end if; 


PRINT.ARRAY; 

end loop; 


(Continued on next page) 
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Example 7-1 (Cont.): Interactive Array Sort Using Tasks 


exception 

when end_ERR0R => 

PUT_LINE("That's all folks!"); 

when others => 

PUT_LINE("You've made a mistake; try again"); 
SKIP.LINE; 

TASKSORT; — recall main program 

end USER; 

begin — activate all tasks (GRANTOR, QUICK, USER); 

-- all tasks depend on environment task created 
-- for main program TASKSORT 

null; 

end TASKSORT; 


7.2 Task Storage Allocation 

Each task created in your program requires a certain amount of storage. 
Because VAX/VMS is a virtual memory operating system, the number 
of tasks you can create is limited only by the amount of virtual storage 
available to your process. 

The following sections discuss task storage allocation, and explain how 
you can control it and how it can be important in a mixed-language 
environment. 


7.2.1 Storage Created for a Task Object—the Task Control Block 

When your program creates a task object as, for example, in 

task type is MY.TASK; 

T : MY.TASK; 

or 

task type is MY.TASK; 

type MY_TASK_POINTER is access MY.TASK; 

PT : MY_TASK_POINTER; 

PT := new MY_TASK; 

VAX Ada allocates a block of storage—a task control block —to keep 
track of that task's execution. The task control block is released when 
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control leaves the immediate master (another task or a currently executing 
block or subprogram) upon which the task depends—not when the task 
terminates. See Section 7.1 of this manual and Chapter 9 of the VAX Ada 
Language Reference Manual for a definition of masters and dependency. 

The size of a task control block depends on the characteristics of the 
task's type. That is, a task's size increases in proportion to the number of 
single entries in the task type, the total number of members of all its entry 
families, and the number of single entries which have been specified to 
receive ASTs (see Section 7.6). In particular, if you specify an entry family 
with a very large discrete range, for example 

entry X (1..100.000); 

a large amount of storage will be allocated when a task of the type is 
created. In order to maximize execution speed, an entry-call queue is 
allocated for each member of an entry family. 

You can estimate the number of pages to be allocated for a task control 
block as follows: 

TCB.SIZE (pages) 

where 

FIXED-AMOUNT 
E 

AST_E 


= (FIXED.AMOUNT + E*12.2 + AST_E*28)/512 


= 3000 

= the number of single entries plus the number of members 
in all entry families 

= the number of single entries that have been specified to 
receive ASTs; that is, those entries declared with pragma 
AST-ENTRY 


For most task types (that is, those having fewer than a few hundred total 
entries), the storage consumed by the task control block is relatively small. 
Note that the main task has no entries. 

You can reduce the size of the task control block by reducing the number 
of entries, the number of entry family members, and the number of entries 
that have been declared with pragma AST_ENTRY. In addition, you can 
cause the storage consumed by a task control block of a terminated task 
to be released by arranging for control to leave its immediate master; see 
Example 7-2. 
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Example 7-2: Leaving a Master to Release a Task Control 
Block 


procedure RELEASE is 
task type S0ME_TASK; 

type OUTER_ACCESS is access S0ME_TASK; 

task body SOME.TASK is 
begin 

delay 0.5; -- Simulate doing some useful work, 

end SOME.TASK; 


begin 

-- This loop creates 100,000 tasks. X is assigned 
-- to refer to each new task in turn. Each task 
-- terminates a short time after creation. 


for I in 1..100000 loop 
declare 

type ACCESS_T0_TASK is access S0ME_TASK; 
X : ACCESS_T0_TASK; 


begin 

X := new S0ME_TASK; 

delay 1.0; -- Wait long enough to be sure that 

-- X is terminated. 

end; -- Await termination of all tasks 

-- referred to by type ACCESS_TO_TASK, 
-- and free their storage. 

end loop; 


end RELEASE; 


-- Await termination of all tasks 
-- referred to by type OUTER_ACCESS, 
-- and free their storage. 


Note that storage for only one task control block is consumed at any one 
time, even though 100,000 tasks are created. This is because the block is 
the immediate master of tasks declared to be of type ACCESS_TO_TASK. 
If X were instead declared to be of type OUTER-ACCESS, storage for 
100,000 task control blocks would need to be allocated (even though all 
but one are terminated), and the raising of the exception STORAGE- 
ERROR would be very likely. 


Tasking 7-11 




Thus, when your program creates and terminates many tasks, in order to 
reduce the accumulated storage for terminated tasks, you should arrange 
the program so that the immediate master on which the task depends 
is as "innermost" as feasible. This strategy, however, saves space at the 
expense of more execution time. To minimize execution time, an opposing 
strategy should be followed: arrange the program so that task types and 
task declarations are as "outermost" as feasible to minimize the number of 
tasks that are created and terminated. 


7.2.2 Storage Created for a Task Activation—The Task Stack 

Each time a task is activated, a task stack is allocated. The storage for the 
task stack is released as soon as the task is terminated. 

The stack for a main task is allocated in the PI region of the process in 
which the program is running. The stack of the main task has no definite 
limit; as long as your process has not used up all of its virtual memory, 
the main task stack is automatically expanded as needed. 

The storage for all other tasks is allocated in the PO region. The task 
stack allocated for any of these tasks has two areas: a working storage 
area and a top guard area. The working area is used during normal task 
execution for the storing of variables, call frames, and so on. The top 
guard area is a set of pages (512 bytes per page) at the top of the stack. 
These pages are inaccessible to your program—that is, attempts to read or 
write them will cause a hardware access violation (SS$_ACCVIO), which 
will usually terminate your image immediately. The purpose of these 
guard pages is to help you detect accidental overflow of the working area 
of the stack. Accidental stack overflow can occur, for example, when a 
task executes non-Ada code for which stack checking is not performed 
(see Section 7.2.4), or when storage size checks are suppressed when you 
compile the program (see Section 6.1.4). 

Unless you specify otherwise, the size of the working area and the top 
guard area of a stack are set by the VAX Ada run-time library. By default, 
the working area is set to 60 pages, and the top guard area is set to 10 
pages. The next section tells you how you can change them for any task 
type. 

The default stack allocation for tasks allows an additional 10 pages of 
stack for calls to non-Ada routines, which is adequate for most routines, 
including VAX/VMS system service and Run-Time Library routines. 
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7.2.3 Controlling the Size of a Task Stack 


You may need to specify the sizes of a task's stack areas for a number of 

reasons: 

• You may find that the task is raising the exception STORAGE-ERROR, 
and you want to increase its working area. 

• You may find that the task does not need all of its default stack 
allocation, and you may wish to reduce the working area so that the 
unused storage can be put to other use by your program. 

• You have not called any non-Ada routines, and you are not having 
any stack overflow (you have not suppressed checks and STORAGE- 
ERROR is not being raised). You may thus wish to decrease the top 
guard area and put the storage to other use. 

• You may suspect that some non-Ada routine might be overflowing the 
stack, and you may wish to increase the top guard area in an attempt 
to detect the overflow. 


To control a task's working storage area, you can use the STORAGE—SIZE 
representation attribute. For example, the attribute 

for NEEDS_BIG_STACK'STORAGE_SIZE use 300*512; 

sets the working storage size for the task type NEEDS—BIG—STACK to 
300*512 bytes (that is, 300 pages). 

If you specify a size of zero (bytes), the default stack size is used. 
Regardless of what size you specify, at least three pages of additional 
space are allocated for task management purposes. See Chapter 13 of the 
VAX Ada Language Reference Manual for a description of the syntax and 
use of STORAGE-SIZE. 

There are several methods that you can use to determine the amount of 
storage you need for the stack working area. The simplest method is to 
estimate the storage by analyzing your Ada program. To estimate, you 
must account for the largest number of Ada frames (including blocks) that 
your task can call (or elaborate, if the frame is a block) at any one time. 
For each frame, allow 76 bytes minimum plus 

• The sum of the sizes of all local objects (including formal parameters) 
declared in that frame. 

• Four bytes for each actual parameter. 

• A half page (256 bytes) for each raise; statement. 
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Thus, the estimate for the following subprogram would be 80: 

procedure ESTIMATE is -- 76 bytes for the call frame 

I: INTEGER := 0; — 4 bytes for the local object 

begin 

null; 

end; — 80 bytes total 

A second method is to execute the program with the debugger, and use 
the task debugging features for examining changes in stack storage as the 
program executes (see Developing Ada Programs on VAX/VMS for more 
information). 

To control the stack's top guard area, you can use the pragma TASK— 
STORAGE. For example, the statement 

pragma TASK_ST0RAGE(NEEDS_BIG_STACK, 0) 

sets the top guard area of the task type NEEDS_BIG_STACK to zero. See 
Chapter 13 of the VAX Ada Language Reference Manual for a description of 
the syntax and use of pragma TASK-STORAGE. 

Example 7-3 illustrates how the stack areas can be controlled using the 
STORAGE—SIZE attribute and the pragma TASK—STORAGE. 


7.2.4 Stack Overflow and Non-Ada Code 

You are protected from stack overflow in an Ada program because VAX 
Ada raises the exception STORAGE—ERROR when an attempt is made 
to overflow either the main stack or an Ada task stack. In addition, the 
default 10-page stack storage allocated for each non-Ada call should be 
adequate protection against stack overflow for most non-Ada routine 
calls (see Section 7.2.2). However, you should be aware that non-Ada 
routines, system services, Run-Time Library routines, and so on do not 
check for stack overflow. Thus, when you call a non-Ada routine from 
an Ada program, it could be possible that the stack of the main task or 
an individual task would overflow, and the Ada program would not be 
able to detect it because the exception STORAGE—ERROR would not be 
raised. Such an undetected stack overflow could result in random changes 
to various locations beyond the storage allocated for the stack. Because 
the correct operation of the Ada program may depend on such locations, 
undetected stack overflow could make your program erroneous. 

Thus to be safe, you should not mix Ada and non-Ada programs without 
checking for stack overflow. You can use the top guard areas of tasks in 
your program to detect if a non-Ada routine causes the stack to overflow 
(see Section 7.2.2 for information about the top guard area). If you make 
the size of the guard pages in the top guard area large enough, then 
undetected overflows that are not larger than the guard pages will raise a 
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hardware access violation (SS$_ACCVIO) exception, which will usually 
terminate your image immediately. 

The VAX/VMS Symbolic Debugger can be of great help in detecting stack 
overflow. The debugger will perform an automatic stack check for you, 
and can display the amount of stack space in use in any task. For further 
information, see Developing Ada Programs on VAX/VMS. 

Example 7-3: Controlling the Size of a Task's Stack 


procedure CONTROL is 

task type NEEDS_BIG_STACK; 

for NEEDS_BIG_STACK'STORAGE_SIZE use 30000*76; 

-- Set the stack working area of tasks of type 
-- NEEDS_BIG_STACK so they can handle the deepest 
-- call of the recursive procedure CALL_SELF. 

— (The value 76 is sufficient storage for one 
-- activation of procedure CALL_SELF.) 

pragma TASK_ST0RAGE(NEEDS_BIG_STACK, 0); 

— Decrease the top guard area of the stack to 0 because 
-- the task NEEDS_BIG_STACK does not call outside Ada. 

-- Hence, no guard pages are needed. 

T : NEEDS_BIG_STACK; 

task body NEEDS_BIG_STACK is 

procedure CALL.SELF (I : INTEGER) is 

begin 

if I < 30000 then 
CALL.SELF(I +1); 

end if; 

end CALL.SELF; 

begin 

CALL .SELF (1) ; 
end NEEDS.BIG.STACK; 

begin 

null; 

end CONTROL; 
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7.3 Task Switching 


VAX Ada implements the Ada language requirement that when two tasks 
are eligible for execution, and they have different priorities, the lower 
priority task will not execute while the higher task is waiting. Thus, the 
VAX Ada run-time library keeps a task running until either it is suspended 
or a higher priority task becomes ready. 

NOTE 

The term "suspend" is used in this chapter (as it is used in the 
VAX Ada Language Reference Manual) to mean that execution of 
the task is temporarily stopped—the task is waiting for another 
event, such as the acceptance of an entry call, to occur before 
execution resumes. "Suspend" does not refer to the VAX/VMS 
system service $SUSPND. 

By default, VAX Ada does not switch from a running task to another 
task of the same priority unless the running task becomes suspended 
(for example, for a delay, entry call, input-output request, and so on). 

This first-in-first-out (FIFO) scheduling strategy tends to minimize task 
switching overhead. It also has the beneficial effect of increasing the 
repeatability of tasking events from one run of the program to the next. 

However, FIFO scheduling is not necessarily "fair" to tasks of equal 
priority that are eligible for execution but not yet running. These waiting 
tasks can exhibit sluggish response times, especially if they are interacting 
with a terminal. They will, in fact, never get to run if the running task 
does not become suspended. FIFO scheduling permits a running task to 
"capture" the processor. 

You can use the pragma PRIORITY to give the more important tasks 
higher priorities, and thus increase their responsiveness. The range of 
possible VAX Ada task priorities is from 0 to 15; in the absence of this 
pragma, VAX Ada tasks have a default midrange priority of 7. (Note 
that task priority has no affect on the priority of your process; from the 
VAX/VMS point of view, the process priority applies to the execution of 
every task in your program.) For example, the statements 

task IMPORTANT.TASK; 

HIGH_PRIORITY: constant := 14; 

pragma PRIORITY(IMPORTANT.TASK, HIGH_PRIORITY); 
end IMPORTANT_TASK; 

set the priority of the task IMPORTANT-TASK to 14. This pragma can 
appear only in a task specification or in the outermost declarative part of 
a main subprogram. See Chapter 9 of the VAX Ada Language Reference 
Manual for a description of the syntax and use of pragma PRIORITY. 
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If, instead, you want to increase the fairness of the scheduling by limiting 
the execution time for any particular task, you can specify a time slice with 
the VAX Ada pragma TIME-SLICE. By specifying a time slice, you change 
the default FIFO scheduling strategy to what is known as round-robin 
scheduling. Round-robin scheduling causes tasks of the same priority to 
take turns at the processor, thus preventing a nonsuspending task from 
capturing the processor. 

You specify a time slice as follows: 

pragma TIME_SLICE(static-expression); 

where the static expression is of type SYSTEM.DURATION. A value of 
0.0 (the default) or less disables time-slicing. This pragma has an effect 
only if it appears in the outermost declarative part of a main program; 
see Chapter 9 of the VAX Ada Language Reference Manual for a complete 
description. 

If you specify a time slice, you must realize that, while you are increasing 
fairness, you are paying a price in terms of increased task switching 
overhead (the overhead increases for smaller values of TIME_SLICE) 
and more difficult debugging. Time slice values below 0.01 second are 
not recommended because the smallest time increment supported by the 
VAX/VMS operating system is 0.01 second. 


7.4 Special Tasking Considerations 

Use of tasks in an Ada program requires some care, because, like any other 
language construct, tasking has its own characteristic set of programming 
pitfalls. (Infinite looping, for example, is a characteristic pitfall of while 
loops.) 

The following topics are discussed in this section: deadlock, busy waiting, 
abort statements, interrupting program execution with CTRL/Y, shared 
variables, and reentrancy. 


7.4.1 Deadlock 

Deadlock is a condition in which each task in a group of tasks is sus¬ 
pended and no task in the group can resume its execution until some 
other task in the group executes. Deadlock is also called "circular wait". 

The possibility that Ada tasks may deadlock is a property of the Ada 
language. You can eliminate deadlock through careful program design. 

In addition, the VAX/VMS Symbolic Debugger provides special task 
debugging commands that can help you detect deadlocks; see Developing 
Ada Programs on VAX/VMS. 
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The following examples illustrate some of the more common forms of 
Ada deadlock: self-calling, circular-calling, dynamic-circular-calling, and 
exception-induced. 

A task that calls one of its own entries creates a self-calling deadlock. The 
call cannot be completed until the call is answered, and the call cannot 
be answered because the task itself becomes suspended at the call. Self¬ 
calling deadlock becomes more subtle if the task calls a procedure that 
calls the task. Example 7-4 illustrates self-calling deadlock. 

Example 7-4: A Self-Calling Deadlock 


procedure SELF.CALL is 
task type T is 
entry E; 
end T; 

Y : T; 

procedure P(X : T) is -- Calls entry E in task X. 

begin 

X.E; 

end P; 

task body T is 
begin 

P(Y); -- Never returns. 

accept E; 
end T; 
begin 
null; 

end SELF.CALL; 


A task can cause a circular-calling deadlock when it calls another task 
which calls another task, and so on, and the last task calls the first task. 
One way you can eliminate circular-calling deadlock is by restricting your 
program so that task calls form a strict hierarchy. Example 7-5 illustrates 
circular-calling deadlock. 

A task can cause a dynamic-calling deadlock when a series of entry calls 
forms a circle as in either of the above two cases, but at least one of the 
calls is a timed or conditional entry call in a loop that completes only if 
the rendezvous occurs. Thus, with dynamic-calling deadlock, at least one 
task is executing, but no progress can be made. Example 7-6 illustrates a 
dynamic-calling deadlock. 
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Example 7-5: A Circular-Calling Deadlock 


procedure CIRCULAR.CALL is 
task type T1 is 
entry E; 
end Tl; 

task type T2 is 
entry E; 
end T2; 

Y : Tl; 

Z : T2; 

procedure P is 
begin 
Z.E; 
end P; 

task body Tl is 
begin 

P; 

end Tl; 

task body T2 is 
begin 
Y.E; 
end T2; 

begin 

null; 

end CIRCULAR.CALL; 


An exception-induced deadlock occurs when an exception prevents a task 
from answering one of its entry calls; if the exception had not occurred, 
there would be no deadlock. This type of deadlock occurs when an 
unhandled exception in an Ada task must wait for termination of local 
dependent tasks before propagating. Exception-induced deadlock is more 
subtle than the other kinds of deadlock because, were it not for the 
exception, the program would be deadlock free. Example 7-7 illustrates 
an exception-induced deadlock. 
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Example 7-6: A Dynamic-Calling Deadlock 


procedure DYNAMIC_CALL is 

task type T is 
entry E; 
end T; 

Y : T; 

procedure P(X : T) is 

DONE : BOOLEAN := FALSE; 

begin 

while not DONE loop 
select 

X.E; 

DONE := TRUE; 

or 

delay 0.5; — This alternative is always 

-- chosen. 

end select; 
end loop; 
end P; 

task body T is 
begin 

P(Y); -- Call to P never returns. 

accept E; 
end T; 
begin 
null; 

end DYNAMIC.CALL; 


7.4.2 Busy Waiting and Non-Ada Code 

Busy waiting is a programming technique that repeatedly tests a variable, 
sometimes called a "flag" or a "spin lock", to determine if some event has 
occurred. When the event does occur, another instruction sequence is 
presumed to execute and set the flag, thereby ending the looping. 

Busy waiting is sometimes desirable when an event will occur quickly, and 
it is justifiable to use CPU time to wait for it. It is also desirable when no 
other suitable synchronization methods (such as rendezvous) are available. 
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Example 7-7: An Exception-Induced Deadlock 


procedure EXCEPTION.INDUCED is 
task PARENT is 
entry E; 
end PARENT; 

task body PARENT is 
begin 

declare 

task CHILD; 


UNANTICIPATED.EXCEPTION : exception; 

task body CHILD is -- Exceptions wait for any 
begin — task declared within a 

PARENT.E; -- unit declared within a task. 

end; 


begin 

raise UNANTICIPATED.EXCEPTION; 

accept E; 

end; 


end PARENT; 


— Exception occurs 
-- here; CHILD'S call 
-- never accepted. 

-- Parent waits here 
-- for termination 
-- of child. 


begin 

null; 

end EXCEPTION.INDUCED; 


Busy waiting has some undesirable characteristics, however. First, as¬ 
sumptions about an event that were true when the code was written may 
no longer be true when the code is executed; as a result, a large, unanti¬ 
cipated amount of CPU time may be consumed at execution time. For a 
process running under VAX/VMS, this usually means that the process is 
using processor resources that another process could use to advantage. 

Second, when tasks execute busy-waiting code, the effect can be unpre¬ 
dictable. Assume that one task is executing the wait loop, while another 
task is expected to set the flag. Then, suppose that the task executing the 
busy-waiting code has the highest priority in the program. If time-slicing 
is not enabled, deadlock will develop because the busy-waiting task does 
not suspend and no other task (including the flag-setting task) can be 
scheduled (see Section 7.3 for a discussion of first-in first-out scheduling). 
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(Note that this behavior is in accordance with Ada rules). The situation 
can be improved only slightly if time-slicing is enabled. The deadlock 
can still develop if the flag is to be set by a task of lower priority (even 
with time-slicing, a low-priority task cannot be scheduled while a higher 
priority task is ready). 

Because of these potential problems, you should avoid busy waiting. VAX 
Ada does not use busy waiting, so if your program uses only VAX Ada, 
you should not encounter this kind of deadlock. 

If you do discover that your tasking program is caught in a busy waiting 
loop by some software over which you have no control, you can probably 
correct the problem by setting all of your task priorities to the same value 
(or, equivalently, by eliminating all specifications of pragma PRIORITY) 
and by enabling time-slicing with pragma TIME-SLICE (see Section 7.3). 


7.4.3 Using Abort Statements 

Use of abort statements requires care: use of an abort statement can 
terminate a task when it should not be terminated, and thus can lead to 
erroneous execution. You should use abort statements only when you 
require unconditional termination, and only when you are sure that it 
is safe to do so. For example, if you abort a task with an asynchronous 
system service request in progress (such as QIO), the task can become 
terminated and its stack storage reallocated to some other use before 
VAX/VMS has written the result data. The result data could be written in 
some unexpected part of your program's data area. 

VAX Ada implements the abort statement in a "synchronous" rather 
than an "asynchronous" form. An asynchronous implementation of abort 
can cause completion of tasks at arbitrary points in their execution. The 
synchronous form causes tasks to become completed only at specific 
points in their execution (see of Chapter 9 the VAX Ada Language Reference 
Manual for a list of these points). 

Synchronous abort has several benefits. One benefit is that when a task 
calls a non-Ada routine (and the routine does not result in a call to an 
Ada subprogram), the non-Ada routine will execute to completion even 
though the calling task has been aborted. Synchronous abort thus avoids 
problems that may result because non-Ada routines typically are not 
programmed to work correctly if partially executed. 

Unfortunately, use of synchronous abort also means that a task in an 
infinite loop cannot become completed unless it executes code that is a 
synchronization point for abort. If you want to ensure that a task will 
become completed due to abort in some particular section of code, you 
should insert a delay 0.0 statement there. The Ada language requires 
that an abnormal task become completed at a delay statement; hence. 
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delay 0.0 is a fully transportable and low-overhead means of ensuring 
that completion can occur. 


7.4.4 Interrupting Your Program With CTRL/Y 

When you use CTRL/Y to interrupt the execution of an Ada program 
that contains tasks, you can expect some special side effects when you 
subsequently try to execute DCL commands. The DCL commands that 
you would be most likely to enter after typing CTRL/Y are: DEBUG, 
CONTINUE, EXIT, STOP, or a query like DIRECTORY. For each of 
these (except CONTINUE), the current execution point of the process is 
modified by the VAX/VMS operating system, and execution resumes at 
the new location: 

• CONTINUE causes your program to begin execution at the same point 
at which the CTRL/Y interrupt occurred. 

• STOP immediately terminates execution of your program, as well as 
terminating any tasks that may be active. 

• DEBUG causes the VAX/VMS Symbolic Debugger to be activated, and 
your process to continue its execution under control of the debugger. 

• EXIT causes your program to execute the SYS$EXIT system service. 

• Most other commands, like DIRECTORY, have the effect of first 
executing the EXIT command and then executing the command itself. 


In addition, if a low-priority task is running when you type CTRL/Y, the 
action taken is affected by that task's priority. In particular, because a 
higher priority task may be scheduled almost immediately, the desired 
effect may not occur for a while, or might never occur. (CONTINUE 
and STOP are not affected by the task's priority: CONTINUE because 
continuation makes the interruption irrelevant, and STOP because it does 
not resume execution in VAX user mode, where task switches take place.) 
For example, if you type DEBUG, the debugger may not be immediately 
entered. If you type EXIT, the process may continue execution and not 
exit. If you type DIRECTORY, the result is equivalent to first typing EXIT 
and then the command, so your process may continue executing. 

There are two ways to control the results of using these commands. First, 
you can always force your program to quit by typing STOP. When you 
do this, however, any established exit handlers will not have a chance to 
execute. For example, VAX Ada provides an exit handler for the input- 
output packages, and if you type STOP to interrupt input-output, the VAX 
Ada handler will not have an opportunity to write the last partial record 
to whatever external files may be open at the time, to close those files, or 
to delete Ada temporary files. 
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A second solution is to use the VAX Ada predefined package 
CONTROL—C—INTERCEPTION, which allows you to run the debugger, 
exit the program, or issue a query like DIRECTORY. The operations it 
provides mimic the operations you can perform after typing CTRL/Y. You 
invoke these operations by typing CTRL/C anytime after the package has 
been elaborated. For example: 

-- Enable CTRL/C interception prior to main 
-- program execution (but not necessarily before 
-- all library packages have been elaborated). 

with CONTROL_C_INTERCEPTION; 

pragma ELABORATE(CONTROL_C_INTERCEPTION); 

procedure MY_MAIN_PROGRAM is 

begin 

end MY_MAIN_PROGRAM; 

The following illustrates the response of this handler to CTRL/C: 

Nothing can go wrong 
go wrong 
go wrong 
go wrong 
go wrong 
~C 

Ada CTRL/C Interceptor 

Type: DEBUG, EXIT, CONTINUE, or a DCL command. 

Ada_CTRL/C> DEBUG 
DBG> 

The package specification for CONTROL_C_INTERCEPTION is pre¬ 
sented in Appendix A. 


7.4.5 Using Shared Variables 

One of the effects of using tasks is that variables shared by one or more 
tasks (including the main, or environment task) can be modified asyn¬ 
chronously. That is, the values of shared variables can be modified at 
unpredictable times and their values can thus be uncertain. This uncer¬ 
tainty is increased by optimizations made by the compiler (initial values 
may be saved in and used from registers or copied directly into the 
compiled code, and so on). 
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To guarantee that the value of a shared variable is updated or read 
from the storage allocated for the variable (and not from a copy or a 
register), VAX Ada provides pragma VOLATILE. Chapter 9 of the VAX 
Ada Language Reference Manual gives the Ada language assumptions 
about shared variables and gives the usage rules and syntax for pragma 
VOLATILE. The syntax is given here for convenience: 

pragma VOLATILE (variable-simple-name); 

Note that pragma VOLATILE is not needed for variables that are implicitly 
or explicitly synchronized (such as variables involved in a rendezvous). 

This pragma can be used with variables of any type, including records or 
arrays. As shown in the following example, pragma VOLATILE can be 
particularly useful for protecting records that serve as input-output status 
blocks in calls to the VAX/VMS system service SYS$QIO: 

with STARLET; 
task body HANDLER is 

IOSB : STARLET.IOSB.TYPE; 

— Pragma VOLATILE assures that the QIO system 
-- service is not passed the address of a copy 
-- of IOSB, but rather its actual memory 

— location, and that the program always 

— references the current value of IOSB. 

pragma VOLATILE(IOSB); 

begin 

QI0( > 

IOSB => IOSB, 

ASTADR => RECEIVE.AST'AST.ENTRY, 

. • • ); 
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accept RECEIVE_AST do 

-- Because IOSB is volatile, the reference 
-- to IOSB.STATUS is not a reference to a 
-- temporary copy, but to the original 
-- IOSB. 

if CONDITION.HANDLING.SUCCESS(IOSB.STATUS) then 
end if; 

end RECEIVE.AST; 
end HANDLER; 

In this example, the program examines the status block only after the 
service has completed (completion is assured when the accept statement 
is executed). Pragma VOLATILE makes it possible to "poll" the status 
block while waiting for the service to complete, but, because polling is a 
kind of busy waiting that takes a fair amount of CPU time, it is usually 
much better to use a synchronized event to determine completion. For 
example, you could synchronize a task with event flag wait completion, 
AST delivery, rendezvous with another task, and so on. 

This pragma does not guarantee indivisible access; that is, it does not keep 
more than one task from accessing the storage for a variable. What it 
does guarantee is that the actual storage (and not another copy) will be 
accessed. To ensure indivisible access for a variable in your program, you 
must ensure that sharing of the variable is synchronized. 


7.4.6 Reentrancy 

In most VAX languages, three kinds of reentrancy are possible: serial, 
recursive, and AST reentrancy. A fourth kind, full reentrancy, is important 
for Ada programs that have tasks. 

A routine is serially reentrant if it must execute to completion before it 
is allowed to be called again. FORTRAN routines are usually serially 
reentrant. 

To understand recursive reentrancy , consider a routine that executes to the 
point of another call to itself; it makes the call to itself (a recursive call), 
and then continues to make recursive calls until a statement is executed or 
a condition occurs that ends the recursion. Then, the statements after the 
point of the recursive call execute, until finally the original call completes. 
If no calls are permitted until the original call has completed, the routine 
is said to be recursively reentrant. A recursively reentrant routine is also 
serially reentrant. 
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AST reentrancy means that at a random point during the execution of a 
routine, an AST can occur and the routine may be reentered (by the AST 
call). The VAX/VMS operating system does not normally allow more than 
one AST service routine to be called at a time for any given access mode. 
So, if a routine is AST-reentrant, it may be designed to permit at most two 
calls to be in progress at any one time. An AST-reentrant routine is also 
serially reentrant. 

A routine is fully reentrant if it gives correct results when called by mul¬ 
tiple tasks whose execution can be suspended at arbitrary points (and 
resumed in arbitrary orders) in the routine's code. A routine that is fully 
reentrant is also necessarily AST reentrant, recursively reentrant, and 
serially reentrant. 

The following sections discuss reentrancy in the context of mixed-language 
programs involving Ada tasks. Unless explicitly qualified, the term reen¬ 
trant denotes full reentrancy. 


7.4.6.1 Reentrancy in Mixed-Language Tasking Programs 

You must be careful when calling non-Ada routines from VAX Ada tasks 
because the results will be unpredictable if the routines are not fully 
reentrant. All VAX/VMS system service, and most Run-Time Library, 
routines are fully reentrant. In particular, the language-independent Run¬ 
Time Library routines (LIB$, MTH$, OTS$, SMG$, and STR$ routines) 
are generally fully reentrant (see the VAX/VMS Run-Time Library Routines 
Reference Manual). However, any routine that modifies variables outside 
its immediate scope or that modifies variables allocated in static storage is 
potentially nonreentrant. Also, any language-dependent Run-Time Library 
routines may be nonreentrant. For example, the FORTRAN Run-Time 
Library is only AST (not fully) reentrant. 


7.4.6.2 Avoiding Nonreentrancy 

The simple subprogram in Example 7-8 illustrates that if you allow a 
nonreentrant Ada subprogram (or non-Ada routine) to be reentered, the 
results can be unpredictable. 
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Example 7-8: A Nonreentrant Subprogram 


package CONTAINER is 

-- Function to return 1 + I (its argument) 

function NONREENTRANT(I : INTEGER) return INTEGER; 
end CONTAINER; 

package body CONTAINER is 

GLOBAL.VARIABLE : INTEGER := 0; 
function NONREENTRANT(I : INTEGER) 

begin 

GLOBAL.VARIABLE := I; 
return (GLOBAL.VARIABLE + 1); 
end NONREENTRANT; 


return INTEGER is 

-- Statement SI 
-- Statement S2 


begin 

null; 

end CONTAINER; 


In this example, the function NONREENTRANT returns 1 plus the value 
of its argument, I. NONREENTRANT is a serially reentrant subprogram. 
But it cannot be called simultaneously by multiple tasks and still produce 
correct results. For example, suppose it is called by task A, which passes 
a value of 3 for I, and then A is interrupted just before statement S2 
because a higher priority task, B, has become ready. Then, suppose B calls 
NONREENTRANT and passes a value of 1000 for I (that is, B "reenters" 
the subprogram, while a previous call is in progress). Although the 
execution of NONREENTRANT by A set GLOBAL-VARIABLE to 3, the 
intervening execution by B has changed the global variable to 1000. When 
task A finally resumes execution, NONREENTRANT returns a value of 
1001, instead of the correct answer, 4. 

There are three ways to avoid the problem shown in Example 7-8: (1) 
write the routine or subprogram so that it is reentrant, (2) ensure that only 
one task can call the nonreentrant routine or subprogram, or (3) serialize 
the calls to the nonreentrant routine or subprogram (see Example 7-10 at 
the end of this section). 

To code a reentrant subprogram in VAX Ada, make sure it does not 
modify any nonlocal or static variables and make sure that it does not call 
a nonreentrant subprogram (or routine). If you import a non-Ada routine, 
be aware that it can be reentered if it is imported several times in the same 
Ada program or if it is imported once and then called from different tasks. 
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In Example 7-9, the function NONREENTRANT from the Example 7-8 
has been rewritten so that it is reentrant. Advantage has been taken of the 
fact that each time a subprogram is entered, its local variables are allocated 
on the stack. If tasks A and B were to call the following subprogram, each 
activation of function REENTRANT would create a separate copy of 
LOCAL-VARIABLE, and interference would not be possible. 

Example 7-9: A Reentrant Subprogram 


function REENTRANT(I : INTEGER) return INTEGER is 
LOCAL.VARIABLE : INTEGER := 0; 

begin 

LOCAL.VARIABLE := I; — Statement SI 

return (LOCAL.VARIABLE + 1); — Statement S2 

end REENTRANT; 


The second solution is to structure your program to ensure that the 
nonreentrant subprogram can only be called by a single task at a time. 

For example, if a procedure is defined in the declarative region of the 
same task that calls it, and the task creates no dependent tasks, then the 
subprogram cannot be reentered. 

The third solution applies especially to existing nonreentrant Ada supro- 
grams, non-Ada routines, or software over which you have no control. 
You can use a task to prevent reentry by "serializing" the calls to the 
reentrant code so that it cannot be reentered. Example 7-10 shows one 
way that serialization can be done. 

In this example, task SERIALIZER calls a nonreentrant subprogram in the 
body of an accept statement. All calls to the nonreentrant code go through 
the intermediate call to ADD—ONE, and function NONREENTRANT 
cannot be reentered. 

You can also use a serializing task to allow nonreentrant routines or sub¬ 
programs to be called from multiple tasks. The serializing task prevents 
reentry—but you must make sure that it makes all the calls. This method 
is recommended when you call any routine or subprogram whose reen- 
trancy is uncertain and you cannot guarantee that reentrant calls will not 
be attempted. 
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Example 7-10: Using a Serializing Task to Prevent Reentry 


package FIX_IT is 

-- This function should be called instead of 
— NONREENTRANT. It too returns 1 + I (its argument), 
function ADD.ONE (I : INTEGER) return INTEGER; 

end FIX_IT; 

with CONTAINER; 
use CONTAINER; 

package body FIX_IT is 

task SERIALIZER is 

entry DO_CALL(I : INTEGER; J : out INTEGER); 

end; 

task body SERIALIZER is 

-- This task calls NONREENTRANT and ensures that it 
-- cannot be reentered. 

begin 

loop 

select 

accept DO_CALL(I : INTEGER; J : out INTEGER) do 
J := NONREENTRANT(I); 

end; 

or 

terminate; 
end select; 
end loop; 
end; 

function ADD.ONE (I : INTEGER) return INTEGER is 
RESULT : INTEGER; 

begin 

SERIALIZER.DO_CALL(I, RESULT); 
return RESULT; 
end; 

end FIX_IT; 


7.5 Calling VAX/VMS System Service Routines from Tasks 

VAX Ada provides the package STARLET (see Chapter 5) as well as 
import-export pragmas (see Chapter 4) to allow you to call VAX/VMS 
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system services and make RMS requests directly from an Ada program. In 
addition, VAX Ada provides a package of selected asynchronous system 
routines—TASKING—SERVICES—to make such routine calls easier to 
make from tasks. The following sections discuss the implications of calling 
system routines from tasks. 


7.5.1 Effects of System Service Calls on Tasks 

When you call VAX/VMS system services from an Ada program, your pro¬ 
cess is not totally "blocked". Most system services that put your process 
in a wait state permit that wait state to be interrupted by asynchronous 
system traps (ASTs) (see the VAX/VMS System Services Reference Manual). 
To VAX Ada, a task that has entered a VAX/VMS wait state appears to 
be continuing to execute (since VAX Ada does not in any way "intercept" 
system services); VAX Ada does not know that the task is in any way 
"blocked". 

Thus, the only tasks that can execute while the system service is executing 
are tasks that have higher priorities than the calling task, or, if time-slicing 
is in effect, tasks that have priority equal to the calling task. (The transfer 
of control to these other tasks can occur when an AST for one of these 
tasks is delivered to the VAX Ada run-time library—for example, when a 
delay or time-slice expires, an Ada input-output request completes, or an 
AST is delivered to a task entry specified with pragma AST_ENTRY.) 

This default behavior is not necessarily bad, because waiting for the 
system service to complete is the default behavior of most nontasking 
VAX/VMS programs. Indeed, if the request is satisfied quickly, allowing 
any other task to execute could be totally wasted effort. 

You may, however, wish to "increase concurrency" and allow tasks of 
lower priority to execute while a higher priority task is in a VAX/VMS 
wait state. Provided that the system service request takes a sufficiently 
long time, this strategy can allow your program to get more useful work 
accomplished in the same elapsed time. 

VAX Ada provides you with two ways to increase concurrency during a 
VAX/VMS system service wait interval. One way is to have tasks that 
call time-consuming system services use asynchronous system services 
or asynchronous RMS services. Then your program can do other work 
until it has to handle the resulting VAX/VMS asynchronous system traps 
(ASTs) that signify completion of the request. Handling ASTs is a very 
general and powerful way to increase concurrency, but it also requires 
more detailed programming. See Section 7.6. 
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The second way to increase concurrency is to use the VAX/VMS sys¬ 
tem routine operations provided in the VAX Ada package TASKING— 
SERVICES. Like the system routines provided in package STARLET, 
the operations in this package provide an interface to a variety of 
VAX/VMS system service and RMS routines. But the operations in 
package TASKING—SERVICES are designed to suspend (in the Ada sense) 
the calling task if the request cannot be immediately satisfied. Other ready 
tasks (including lower priority tasks) in your program are free to execute 
or continue executing. 

The operations in package TASKING—SERVICES increase concurrency 
by calling the asynchronous form of system service routine (for example, 
SYS$QIO instead of SYS$QIOW), and then suspending the task and using 
an AST to signal when the service has completed and the execution of the 
task can resume. The details of AST handling are hidden by the package. 

While this package can help you increase concurrency, in many cases, it 
has two limitations: you cannot use the operations in package TASKING— 
SERVICES to specify an AST routine address or an AST parameter. If 
your application depends on being able to use such information, you may 
wish to do your own AST handling as described in Section 7.6. 

The specification of package TASKING—SERVICES is presented in 
Appendix A. 


7.5.2 System Services Requiring Special Care 


Certain system services are especially likely to interfere with Ada pro¬ 
grams that use tasks, ASTs, or the package TASKING—SERVICES (see 
Section 7.5.1). It is recommended that you either avoid or use extra care 
when using the following services: 


SYS$SETAST 

SYS$HIBER 

SYS$EXIT 

SYS$DCLEXH 


STARLET.SETAST 
STARLET.HIBER 
STARLET.EXI 
STARLET.DCLEXH 


Because they affect a VAX/VMS process, these services have a "global" 
effect on all tasks of the program. For example, SYS$SETAST prevents 
delivery of ASTs. Because the VAX Ada run-time library relies heavily 
on the use of ASTs (they are used to implement delay statements, time¬ 
slicing, input-output, and so on), disabling ASTs with SYS$SETAST can 
cause deadlocks (see Example 7-11). This effect can cause these tasks to 
stall until ASTs are reenabled. 
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Example 7-11: Deadlock Caused by Call to SYS$SETAST 


procedure SETAST_DEADLOCK is 

task T is 
entry E; 

end; 

task body T is 

begin 

delay 10.0; 
accept E; 

end; 

-- Procedure to set AST enablement to SETTING. 

procedure SETAST(SETTING : BOOLEAN) is separate; 
begin 

SETAST(FALSE); 

T.E; -- At this point, task T is delayed, waiting 

— for the timer AST that signifies the end of 
-- the wait. The following entry call must suspend 
-- because the task has not reached the accept. 

-- But, since the call to SETAST has disabled ASTs, 
-- the delay will never complete, and thus neither 
-- will this entry call. 

SETAST(TRUE); 

end; 


If it is necessary for you to use SYS$SETAST, while ASTs are disabled 

you must not 

• Execute Ada input-output statements (for example, TEXT_IO.PUT- 
LINE). 

• Execute a delay statement. 

• Propagate an unhandled exception. 

• Execute any of the tasking operations described in Chapter 9 of the 
VAX Ada Language Reference Manual (for example, make entry calls, 
execute accept or select statements, and so on). In other words, you 
must not create or wait for dependent tasks. 

• Busy wait on a flag (a variable) that is to be set by another task. 

• Call a subprogram that involves any of the preceding actions. 
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SYS$HIBER suspends execution of a VAX/VMS process. The VAX Ada 
run-time library uses SYS$HIBER to make your process hibernate when 
there are no currently ready tasks. If your program also uses SYS$HIBER, 
you should make sure that the SYS$WAKE it is waiting for is issued only 
when the process is waiting for your SYS$HIBER request (and not for the 
SYS$HIBER request of the VAX Ada run-time library)—the SYS$WAKE 
you issue may be consumed by the call to SYS$HIBER of VAX Ada, and 
your hibernate will not wake up. 

SYS$EXIT causes an unconditional program exit. In particular, it does not 
wait for dependent tasks to terminate normally. Thus, its use may prevent 
the Ada program from executing code that it would otherwise execute 
normally. Unless you are careful that all tasks are terminated or in a state 
where termination is not needed, the results can be unpredictable. See 
Example 7-12. 

Example 7-12: Unpredictability of SYS$EXIT 


with TEXT.IO; use TEXT_I0; 
procedure PULL_THE_RUG_OUT is 

pragma TIME.SLICE (1.0); 

type CONDITION is new INTEGER; 

STATUS : CONDITION; 

task T; 

task body T is 
begin 

for I in 1. . 10 loop 

PUT_LINE("I'm T and I'm not done yet"); 
delay 1.0; 
end loop; 

PUT_LINE("T is done now"); 

end; 


(Continued on next page) 
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Example 7-12 (Cont.): Unpredictability of SYS$EXIT 


procedure DCLEXIT(STATUS : out CONDITION; 

EXIT_STATUS : in CONDITION := 1); 
pragma INTERFACE(VMS. D0_EXIT); 
pragma IMPORT_VALUED_PROCEDURE(D0_EXIT. 

"SYS$EXIT", 

MECHANISM => (VALUE. VALUE)); 


begin 

delay 5.0; 

PUT_LINE("Pulling the rug out from T NOW"); 
DO.EXIT(STATUS); 

end; 


If you use SYSSDCLEXH to establish exit handlers, you should make 
sure that a special VAX Ada exit handler is established last (and therefore 
executed first) to ensure that, once started, exiting will continue. (The 
effect is that exiting will occur with a high priority.) 


7.6 Handling Asynchronous System Traps (ASTs) 

Asynchronous system traps (ASTs) are a way for VAX/VMS or RMS 
to notify a process (which may be actively executing instructions) that 
some event has occurred. Many system services allow you to specify 
that an AST be delivered when the service completes or when some 
event related to the service occurs. Such services often have two forms: 
a synchronous form that forces the process to wait until the service is 
completed; and an asynchronous form that initiates the service, and 
immediately returns, allowing the process to continue and the service to 
be completed independently. For example, the synchronous VAX/VMS 
service SYS$QIOW makes the process wait until the service completes, 
but the asynchronous form, SYS$QIO, does not; both forms allow you to 
specify an AST service routine. 

By handling ASTs from your Ada program, you can increase concur¬ 
rency during process wait states resulting after your program executes 
certain system service or RMS requests. Before you decide to handle 
ASTs directly, however, you should investigate the package TASKING— 
SERVICES to see if you can use any of its operations instead (which are 
more convenient to use); see Section 7.5.1. 


Tasking 7-35 



7.6.1 


Pragma AST_ENTRY and the AST—ENTRY Attribute 


You can handle—and it is recommended that you handle—ASTs in VAX 
Ada with the AST—ENTRY pragma and AST—ENTRY attribute. 

For a formal description of the AST_ENTRY pragma and attribute, see 
Chapter 9 of the VAX Ada Language Reference Manual. Informally, the 
AST_ENTRY pragma and attribute provide a mechanism that transforms 
the delivery of an AST into a special kind of entry call. As in an ordinary 
entry call, if the task does not immediately accept the call, the AST entry 
call becomes enqueued on the entry. 

with STARLET; use STARLET; 

task HANDLER is 

entry RECEIVE.AST; 

-- Entry RECEIVE_AST is now permitted to 
-- receive AST entry calls as well as normal 
— entry calls. 

pragma AST_ENTRY(RECEIVE_AST); 
end HANDLER; 


-- The AST—ENTRY attribute supplies QIO's ASTADR parameter 
-- with the address of a special AST handler that will 
-- schedule an entry call to RECEIVE_AST. 

QIO( • • • 

ASTADR => HANDLER.RECEIVE.AST'AST.ENTRY, 

. . . ); 


An AST entry call acts as if the call were made by a task that has priority 
8. In accordance with Ada rendezvous rules, the statement list of the 
accept statement for this entry is executed with the higher of this priority 
and the priority of the accepting task. 

The AST parameter passed to the system service (for example, the astprm 
argument of the SYS$QIO system service) and later delivered by the 
AST is, in turn, passed to the accept statement (if a formal parameter is 
specified): 
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with STARLET; use STARLET; 


task HANDLER is 

-- Entry RECEIVE_AST expects to receive an 
-- AST parameter. 

entry RECEIVE_AST(X : INTEGER); 
pragma AST_ENTRY(RECEIVE_AST); 

end HANDLER; 


-- QIO's ASTPRM parameter (with a value of 33) is 
-- passed to the accept statement as parameter X 
-- when the rendezvous occurs. (An AST entry can 
-- receive only 0 or 1 parameter.) 

QIO( . . . 

ASTADR => HANDLER.RECEIVE.AST'AST.ENTRY, 
ASTPRM => 33); 

accept RECEIVE_AST(X:INTEGER) do 
end RECEIVE.AST; 


Thus, to handle ASTs, you must first specify which entry in a task type 
can receive AST entry calls. You do this by specifying the entry with 
pragma AST_ENTRY when you declare the task type. Only single entries 
(not entry families) can receive AST entry calls (and, therefore, can be 
named in pragma AST_ENTRY). 

To specify an AST service routine, you must use the AST_ENTRY at¬ 
tribute. The AST_ENTRY attribute takes a task name and entry as 
parameters and returns an address of a special service routine created by 
the VAX Ada run-time library. Then, when the AST occurs, the special 
service routine is called; the routine enqueues the AST parameter in a 
special way on the requested entry, making the enqueuing look like an 
entry call, and then the routine returns from the AST call. 

Once the AST parameter has been enqueued on the entry, the rendezvous 
can occur. Note that the rendezvous is subject to the Ada rendezvous 
rules (see Chapter 9 of the VAX Ada Language Reference Manual), and so 
may not occur immediately. It is important to note that the rendezvous is 
performed after the special service routine has returned. Thus, other ASTs 
are not inhibited. (This behavior is required by the nature of ASTs and 
the nature of Ada rendezvous.) 
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If the entry call were made directly from the AST service routine, no 
other ASTs could be delivered until the rendezvous was completed, and 
unpredictable deadlocks could result. Such deadlocks still could develop 
if a non-Ada program were to call an Ada program from an AST service 
routine. See Section 7.6.3. 


7.6.2 Constraints on Handling ASTs 

Any AST delivered to a task that is completed or abnormal is ignored. 
That is, the AST is ignored if it occurs for some entry of a task that is not 
callable but is not yet terminated (both T'TERMINATED and T'CALLABLE 
are FALSE). 

If, however, an AST occurs for an entry of a task that is terminated 
(T'TERMINATED is TRUE), then the program is erroneous and execution 
is unpredictable. This situation may not be detected by the VAX Ada 
run-time library; you must code your application so that an AST cannot 
occur for an entry in a terminated task. 

Each time an AST is delivered, the VAX Ada run-time library allocates a 
block of storage to hold the AST parameter, and the storage is enqueued 
on the entry to which the AST applies. This block of storage is released 
only after the rendezvous has completed. If your program generates 
ASTs at a higher rate than it accepts AST entry calls, the total amount 
of storage allocated could become very high. To reduce the amount of 
storage consumed, you should write any AST-handling programs so that 
they accept an AST for every AST generated. You can do this easily by 
having the same task that accepts the AST entry call also generate the 
next AST. In this manner, you can limit the amount of storage consumed 
by pending AST entry calls. 


7.6.3 Calling Ada Subprograms from Non-Ada AST Service Routines 

Use of an Ada subprogram as an AST service routine, or the calling an 
Ada subprogram from an AST service routine written in another VAX 
language, requires a great deal of care. If the Ada subprogram performs 
certain kinds of Ada operations, including input-output operations or 
task-related operations, a deadlock can develop (VAX Ada itself uses ASTs 
to perform these operations). If you call such an Ada subprogram from 
an AST service routine, or use it as an AST service routine, your program 
can develop a deadlock with the characteristics that one or more tasks are 
suspended indefinitely and ASTs can no longer be delivered. 
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Such a deadlock can develop in the following manner. Suppose that 
you call Ada subprogram P from a non-Ada AST service routine. The 
AST may be delivered at any time, and when it is delivered, the main 
task or a task Q in your program could possibly have already allocated 
a resource that will be needed by P. (In addition, Q could be currently 
suspended, awaiting the delivery of an AST.) Because the resource is not 
available to P, the VAX Ada run-time library has no choice but to suspend 
the execution of P and switch control to another ready task. But the 
invocation of P occurred when ASTs were disabled, and so ASTs remain 
disabled after P is suspended. Now, a deadlock has developed because P 
cannot proceed until the resource becomes available, the resource cannot 
be released by Q until ASTs are delivered, and ASTs cannot be delivered 
until P and its caller return control back to VMS. All of this occurs because 
VAX/VMS explicitly disables all AST delivery while an AST-handling 
routine is active, unless that routine explicitly reenables ASTs. 

It is strongly recommended that you handle ASTs in VAX Ada as de¬ 
scribed in Section 7.6.1. If you must write AST routines in Ada, then you 
must obey the following rules to avoid the kind of deadlock described 
above. Your routine must not 

• Execute any Ada input-output statements (for example, TEXT_ 

IO.PUT_LINE). That is, your routine must not use any of the input- 
output operations defined in Chapter 14 of the VAX Ada Language 
Reference Manual or in the VAX Ada package TASKING—SERVICES. 

• Execute a delay statement. 

• Propagate an unhandled exception. 

• Execute any of the tasking operations described in Chapter 9 of the 
VAX Ada Language Reference Manual (for example, make entry calls, 
execute accept or select statements, and so on). In other words, you 
must not create or wait for dependent tasks. 

• Busy wait on a flag (a variable) that is to be set by another task. 

• Call a subprogram that involves any of the preceding actions. 


7.6.4 Examples of Handling ASTs from Ada Programs 

Examples 7-13 and 7-14 show the use of pragma AST—ENTRY and the 
AST-ENTRY attribute. 
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Example 7-13: Simple Use of Pragma AST_ENTRY and the AST—ENTRY 
Attribute 


with TEXT.IO, SYSTEM, CONDITION.HANDLING, STARLET; 
procedure TRY_ASTS is 

STATUS : CONDITION_HANDLING.COND_VALUE_TYPE; 
package INT_I0 is new TEXT.10.INTEGER.10(INTEGER); 

-- Task that will service the ASTs fired by the main program. 

task AST.HANDLER is 

entry RECEIVE.AST(X : INTEGER); 
pragma AST.ENTRY(RECEIVE.AST) ; 
end AST.HANDLER ; 

task body AST.HANDLER is 

FORE : constant TEXT.IO.FIELD := 3; 

begin 

loop 

select 

accept RECEIVE.AST(X : INTEGER) do 
INT.IO.PUT(X, FORE); 
end RECEIVE.AST; 

or 

terminate; 
end select; 
end loop; 

end AST.HANDLER; 

begin 

-- Queue 20 ASTs to be fired and give each an index. 

for I in 1..20 loop 
STARLET.DCLASTC 
STATUS, 

-- Condition value returned 
AST.HANDLER.RECEIVE.AST'AST.ENTRY, 

-- Entry to receive the AST 
STARLET.USER.ARG.TYPE (I)); 

-- The AST parameter 


(Continued on next page) 
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Example 7-13 (Cont.): Simple Use of Pragma AST—ENTRY and the 

AST_ENTRY Attribute 


-- If DCLAST fails to queue an AST, then raise the error. 

if not CONDITION.HANDLING.SUCCESS(STATUS) then 
CONDITION_HANDLING.STOP (STATUS); 

end if; 
end loop; 

end TRY.ASTS; 


Example 7-14: Using an AST Entry to Intercept a CTRL/C 


-- Package specification for CONTROL_C_HANDLING 

package CONTROL_C_HANDLING is 
end CONTROL_C_HANDLING; 

-- Package body for CONTROL_C_HANDLING 

with SYSTEM, TEXT_I0, CONDITION.HANDLING, 

STARLET, UNCHECKED.CONVERSION; 
package body CONTROL_C_HANDLING is 

-- Used to specify an outband character to QIOW. 

type SHORT_FORM_TERMINATOR is 

record 

ZERO : SYSTEM.UNSIGNED.LONGWORD; 

MASK : SYSTEM.UNSIGNED.LONGWORD; 

end record; 

CONTROL_C : constant SYSTEM.UNSIGNED_LONGWORD 

:= SYSTEM.UNSIGNED_L0NGW0RD(2**CHARACTER'P0S(ASCII.ETX)); 

TERMINATOR.MASK : constant SHORT_FORM_TERMINATOR 
:= (ZERO => 0, MASK => CONTROL_C); 

STATUS : CONDITION.HANDLING.COND_VALUE_TYPE; 

STATUS1 : CONDITION.HANDLING.COND_VALUE_TYPE; 

CHAN : STARLET.CHANNEL _TYPE; 

TERM.DEV : constant STARLET.DEVICE_NAME_TYPE := "TT:"; 


(Continued on next page) 
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Example 7-14 (Cont.): Using an AST Entry to Intercept a CTRL/C 


-- This task services C0NTR0L_C outband ASTs. 

task AST.SERVER is 

entry CONTROL_C_HANDLER; 

pragma AST_ENTRY(CONTROL_C_HANDLER); 

end AST.SERVER; 

task body AST.SERVER is 

begin 

loop 

select 

accept CONTROL_C_HANDLER do 

TEXT_I0.PUT_LINE("ControL_C was received"); 

end CONTROL_C_HANDLER; 

or 

terminate; 
end select; 
end loop; 

end AST_SERVER; 

function FR0M_AH_T0_UL is 

new UNCHECKED_CONVERSION (SYSTEM.AST.HANDLER, 

SYSTEM.UNSIGNED_LONGWORD); 


begin 

-- Assign a channel to the terminal 

STARLET.ASSIGN(STATUS, -- Condition value returned 

TERM_DEV, -- Terminal device to assign to 
CHAN); -- Channel number 

if not CONDITION_HANDLING.SUCCESS(STATUS) then 
CONDITION.HANDLING.STOP(STATUS); 

end if; 

-- Enable outband ASTs for CONTROL_C, direct the ASTs to AST_SERVER. 

STARLET. G)10W( 

STATUS => STATUS, 

CHAN => CHAN, 

FUNC => SYSTEM."OR"(STARLET.I0_SETM0DE, STARLET.IO_M_OUTBAND), 

PI => FROM_AH_TO_UL(AST_SERVER.CONTROL_C_HANDLER'AST_ENTRY), 

P2 => SYSTEM.TO_UNSIGNED_LONGWORD(TERMINATOR.MASK'ADDRESS)); 


(Continued on next page) 
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Example 7-14 (Cont.): Using an AST Entry to Intercept a CTRL/C 


if not CONDITION_HANDLING.SUCCESS(STATUS) then 

STARLET.DASSGNCSTATUS => STATUS1, CHAN => CHAN); 
CONDITION_HANDLING.STOP(STATUS); 

end if; 

end CONTROL_C_HANDLING; 


-- A program that uses package CONTROL_C_HANDLING. 

with CONTROL_C_HANDLING; 
with TEXT.IO; use TEXT.IO; 
procedure TRY.CONTROL_C is 

begin 

PUT_LINE("Type any number of CTRL/Cs for" & 

"the next 30 seconds."); 

PUT_LINE("CTRL/Cs are trapped and" & 

"serviced by CONTROL_C_HANDLING."); 
delay 30.0; 

NEW.LINE; 

PUT_LINE("Main program terminating ... ") ; 

end CONTROL_C_HANDLING; 


7.7 Measuring and Tuning Tasking Performance 

When you use tasks in your program, you must frequently trade off 
between responsiveness and throughput. Responsiveness is how fast 
a task responds to an asynchronous event, such as a user typing at a 
keyboard. Throughput is how much useful work, as measured by CPU 
time, a program accomplishes in a given amount of elapsed time (time 
spent switching tasks is overhead and takes CPU cycles that could be used 
for useful work). 

In general, if you enable time-slicing via pragma TIME-SLICE, you are 
increasing responsiveness, at the expense of more task-switching overhead 
and therefore decreased throughput. Smaller values of the time-slice 
interval represent higher amounts of this overhead. 

Similarly, if you assign a higher priority to a task, you are opting for 
responsiveness rather than throughput. Assigning a higher priority to 
some task invariably means that the program will perform more task 
switches—every time the high priority task becomes eligible for execution, 
Ada rules require that it displace a currently running lower priority task. 
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In a large program having many tasks, not all of the effects of changing 
the program are immediately obvious. To help you measure the effects 
of a change, VAX Ada provides the DEBUG command SHOW 
TASK/STATISTICS. See Developing Ada Programs on VAX/VMS for 
information on debugging Ada tasks. 
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Chapter 8 

Programming Considerations 


In order to write VAX Ada programs that compile and execute effi¬ 
ciently, you should be aware of certain compiler and language features 
that can affect storage allocation, storage addressing, and code size, 
as well as program compilation and execution times. The topics pre¬ 
sented in this chapter are storage allocation (Section 8.1), use of address 
values (Section 8.2), predefined instantiations (Section 8.3), inlining of 
subprograms (Section 8.4), and compiler optimizations (Section 8.5). 


8.1 Storage Allocation 

To make efficient use of storage from your VAX Ada programs, you 
should know how and where objects are stored. (See Chapter 3 for an 
explanation of how objects and types are represented.) In general, VAX 
Ada objects are stored in registers, on a stack, in static memory, or in 
dynamic memory (on the heap) depending upon their size (and when 
their size is known), their type, how long their lifetimes are, and how they 
are used. 

If registers are available for the lifetime of an object, they are generally 
used to store the object when it is declared in a subprogram, block, or 
task, and it has a scalar, floating-point, or fixed-point type. For example, 
the variables A and B in the following blocks would be stored in registers: 
their scopes do not overlap, their lifetimes are relatively short, and they 
are of the scalar type INTEGER. 
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declare 

A: INTEGER; 

begin 

end; 

declare 

B:INTEGER; 

begin 

end; 

Stack allocation is used for fixed-size local subprogram and task variables 
that cannot be stored in registers. Stack allocation is thus used for objects 
of task types, for fixed-size record and array objects, and for scalar, 
floating-point, and fixed-point objects for which there are no available 
registers. Stack allocation is also used for objects declared with pragma 
VOLATILE, and for objects with which the attribute X'ADDRESS is 
used. For example, the variable A in the following block would be 
stack-allocated (when it might otherwise be register-allocated): 

declare 

A : INTEGER; 

B : SYSTEM.ADDRESS; 

begin 

B := A'ADDRESS; 

end; 

Static memory is used to store constants and fixed-size objects declared 
in library packages. Thus, if you want to guarantee that certain fixed-size 
objects (scalar, floating-point, or fixed-point objects, for example) are likely 
to be stored in registers—and thus improve the execution speed of your 
program—you should not declare them in library packages. 

Dynamic memory is used to store all dynamically sized objects and all 
objects created by allocators. 

Storage is not allocated for unused objects, and objects with constant 
values may be "evaporated". That is, the compiler may incorporate 
the value of compile-time constants into the generated machine code 
instructions, and have no need for a separate object to hold the value. 
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8.2 Working with Address Values 


To allow you to work with storage addresses, the Ada language provides 
the predefined type ADDRESS (in package SYSTEM) and the ADDRESS 
attribute. To avoid difficult-to-isolate problems when working with values 
of this type or values returned by this attribute in VAX Ada, you should 
make sure that you do not use them to 


• Reference an object whose lifetime has expired. 

• Reference an object in an inappropriate manner (for example, you 
attempt to change a declared constant, or the value of an in parameter.) 

• Access storage beyond the end of the amount allocated for an object. 

• Access a variable that is directly referenced in the same subprogram, 
unless that variable has been declared with the pragma VOLATILE. 

• Place a value into a variable which is inconsistent with the variable's 
declared type or subtype. 


If a subprogram body, task body, or library package elaboration code 
uses the ADDRESS attribute of an out or in out formal parameter, or 
of a variable whose declaration does not include a pragma VOLATILE, 
the VAX Ada compiler will implicitly treat that parameter or variable as 
being locally volatile. (Being locally volatile means being volatile for all 
of the immediate body or library package elaboration code; not for any 
surrounding or enclosed subprogram bodies, tasks, or library package 
elaboration code.) 


The effect of this rule is to suppress some optimizations that may not be 
able to detect changes in the value of the parameter or variable caused by 
directly or indirectly dereferencing the value of the ADDRESS attribute. 
(In particular, the value-propagation optimization is suppressed for the 
variable.) 


For example, the statements in the following procedure leave X with a 
value of 0, rather than 1. If X were not implicitly treated as being locally 
volatile (because of the use of X'ADDRESS), the optimizer would generate 
code using the most recent assignment, or 1, when it assigns the value of 
X to Y. However, because X has been marked as being locally volatile, the 
optimizer instead generates code that causes the value at the address of X, 
or 0, to be retrieved when the assignment to Y is made. 
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with SYSTEM; use SYSTEM; 
with UNCHECKED.CONVERSION; 
procedure SHOW.CONVERT is 

type ACCESS.INTEGER is access INTEGER; 

function CONVERT_ADDRESS_TO_ACCESS_INTEGER is 

new UNCHECKED.CONVERSION (ADDRESS, ACCESS.INTEGER); 


X, Y 

: INTEGER; 

VI 

: ADDRESS; 

V2 

: ACCESS.INTEGER; 

begin 



VI := X 1 ADDRESS; 

V2 := C0NVERT_ADDRESS_T0_ACCESS_INTEGER(V1); 
X := 1; 

V2.all := 0; -- X is now 0 

Y := X; — so Y is 0 


end; 

If you make sure that all uses of the value of an ADDRESS attribute are 
contained in the unit where the attribute is evaluated (including a value 
that is passed as a parameter to a subprogram that does not otherwise 
directly or indirectly reference it), the generated code should be free of 
any problematic interactions. 


8.3 Library Level Generic Instantiations 

In VAX Ada, object code is generated for each generic instantiation. 

Thus, if you have a program that makes multiple instantiations of the 
same generic entity (package, subprogram, and so on), the compiler will 
generate code for each instantiation. By creating a library package that 
instantiates the entity and then making that package available to your 
program (by using with and use clauses), you can make your program 
more efficient: code will be generated only once (for the instantiation 
in the library package). You thus save compile time and minimize the 
amount of code generated. 

For example, suppose that you have defined a package containing a 
floating-point type and operations on that type. Also suppose that you 
want to be able to include the predefined VAX Ada mathematics functions 
(in the generic package MATH_LIB) as operations, and you want to be 
able to use TEXT—IO operations to perform input and output. The most 
efficient way of making your type, its operations, and the instantiations 
of MATH_LIB and TEXT_IO.FLOAT_IO available to your program is to 
make a library package as follows: 
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with TEXT_IO; use TEXT.IO; 
with MATH.LIB; 

package MY_FLOAT_TYPE_OPS is 
type MY_FL0AT is digits 13; 

package MY_FLOAT_TEXT_IO is new FLOAT_IO(MY_FL0AT); 
package MY_FLOAT_MATH_LIB is new MATH.LIB(MY.FLOAT); 

end MY_FLOAT_TYPE_OPS; 

When you make this package available to your program (or to parts of 
your program), the instantiations of TEXT—IO.FLOAT—IO and 
MATH—LIB will be done only once (when the package is initially com¬ 
piled and added to your program library), not each time you use them. 

VAX Ada supplies a set of predefined library packages that instantiate 
commonly used generics, notably the generic TEXT—IO packages for inte¬ 
ger and floating-point input and output, and the generic 
MATH_LIB package for floating-point mathematical operations. (See 
Chapter 2, Chapter 5, and Appendix A for the descriptions and specifica¬ 
tions of these predefined packages.) 

Thus, for example if you needed to use the operations in MATH—LIB and 
TEXT—IO.FLOAT—IO many times throughout your program on objects of 
type LONG—FLOAT, you could use the appropriate predefined packages, 
as follows, to save compile time and object code size: 

with L0NG_FL0AT_TEXT_I0; use L0NG_FL0AT_TEXT_I0; 
with LONG_FLOAT_MATH_LIB; use LONG_FLOAT_MATH_LIB; 
procedure MY_MAIN is 
X: LONG.FLOAT; 

begin 

PUT(SIN(X)); 
end MY.MAIN; 

The instantiations of TEXT—IO.FLOAT—IO and MATH—LIB for type 
LONG—FLOAT are thus done once, but are available at all levels of 
MY_MAIN. 
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8.4 Using Pragma INLINE 


To allow you to expand subprograms inline and thereby decrease the 
amount of time spent in making subprogram calls, the Ada language 
provides the pragma INLINE. In VAX Ada, pragma INLINE can affect 
your program either explicitly (you declare a subprogram to be inlined) 
or implicitly (the compiler automatically inlines subprogram bodies under 
certain conditions). The rules for the explicit use of this pragma are given 
in Section 8.4.1; the conditions under which implicit inlining takes place 
are given in Section 8.4.2. 

The syntax and placement rules for this pragma are given in Chapter 6 of 
the VAX Ada Language Reference Manual. 


8.4.1 Explicit Use 

You can use pragma INLINE to explicitly inline a subprogram declaration 
or body provided that the following conditions are true. (A subprogram for 
which pragma INLINE has an effect is "inlinable".) 

• The parameters may not be of 

— a task type 

— a composite type that has components of a task type 
and the result, in the case of a function, may not be of 

— a task type 

— a composite type that has components of a task type 

— an unconstrained array type 

— an unconstrained type with discriminants (with or without defaults) 

• The body of the subprogram may not contain any of the following: 

— a subprogram body, task or generic declaration or body stub (a 
subprogram declaration for an imported subprogram is allowed) 

— a package body (a package specification is allowed) 

— a generic instantiation 

— an exception declaration 

— an access type declaration (a type derived from an access type is 
allowed) 

— any dependent tasks (that is, any constant or variable declaration 
that implies the creation of a task) 
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— any subprogram call that denotes the given subprogram (direct 
recursion) or any containing subprogram, either directly or via any 
renaming 


You can use pragma INLINE for a generic subprogram instantiation, 
for a generic subprogram declaration, or for a subprogram body stub 
declaration, as follows: 

• If you use pragma INLINE for a generic subprogram instantiation, the 
resulting subprogram must satisfy the above restrictions. You can use 
pragma INLINE for an instantiation of a predefined generic declaration 
(such as for UNCHECKED_CONVERSION), but you will not achieve 
any benefit because such instantiations always result in (implicit) inline 
code in any case. 

• If you use pragma INLINE for a generic subprogram declaration, the 
resulting effect is that an implicit pragma INLINE (see Section 8.4.2) 
then applies to every generic subprogram instantiation of that dec¬ 
laration; that implicit pragma is accepted provided the resulting 
subprogram satisfies the above restrictions. (That is, some instan¬ 
tiations may be inlinable, while others may not, depending on the 
characteristics of the generic actual parameters.) 

• If you use pragma INLINE for a subprogram body stub declaration, the 
subprogram signature must satisfy the above restrictions for parameters 
and result. Calls of such stubs are never expanded inline within that 
same unit because the dependent stub is necessarily not available. 

Note that a pragma INLINE contained within a generic declaration or 
template is not checked as such. The check occurs, according to the above 
rules, for each instantiation that results in a (nongeneric) subprogram. 

Also note that code is still generated for an inlinable subprogram in order 
to allow for normal calls (possibly in previously compiled units) that 
cannot be (were not) expanded inline (see the following paragraphs). 

A call to a subprogram is expanded inline provided that 

• The subprogram has pragma INLINE specified and is inlinable. 

• The call is not contained in the result of expanding a call of that same 
subprogram (indirect recursion). 

• The subprogram body is available in either the current unit or in the 
compilation library (the library secondary unit must not be obsolete). 
(Note that the inline expansion of a subprogram body from a unit in 
the compilation library creates a dependency on that unit.) 
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However, a call to a procedure that has an actual type conversion for any 
parameter that is of an array or record type is not expanded inline if the 
mode of that parameter is in out or out. (Thus, some calls of such an 
inlinable subprogram may be expanded and some may not.) 


8.4.2 Implicit Use 

The VAX Ada compiler may assume an implicit pragma INLINE for a 
subprogram body that 

• Satisfies all of the requirements for an inlinable subprogram (see 
Section 8.4.1). 

• Is not a generic instantiation or stub. 

• Is completely local to the current compilation (so that it cannot be 
called from any other unit). 

• Contains no calls to any other inlinable subprogram. 

• Has an estimated size when expanded inline that is no greater (or only 
slightly greater) than the call it replaces. (The estimation of size is 
based on heuristics and is not exact; however, it is designed never to 
be terribly wrong.) 

• Has no parameter of mode in out or out that is of an array or record 
type. 

The compiler may also assume an implicit pragma INLINE for a subpro¬ 
gram created as the result of a library package instantiation. Note in this 
case that calls from other units will be expanded inline; this is safe because 
the package specification and body that result from the instantiation are 
necessarily created together. 

When implicit inlining is done, no code is generated for the subpro¬ 
gram declaration and every call is expanded inline. You can suppress 
this automatic expansion when you compile your program with the 
/OPTIMIZE=SPACE qualifier on the ADA, ACS COMPILE, and ACS 
RECOMPILE commands. See Developing Ada Programs on VAX/VMS for 
more information. 
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8.5 Compiler Optimizations 


The VAX Ada compiler performs a number of standard optimizations 
to improve the quality of the generated code. Specifically, the compiler 
performs 

• Elimination of some common subexpressions. 

• Code hoisting from structured statements, including the removal of 
invariant computations from loops. 

• Inline code expansion for many predefined operations. 

• Rearranging of unary minus and not operations to eliminate unary 
negation/complement operations. 

• Partial evaluation of logical expressions. 

• Global assignment of variables to registers. 

• Forward propagation of constant values. 

• Reordering of the evaluation of expressions to minimize the number of 
temporary values required. 

• Peephole optimization of instruction sequences. 

In addition, the compiler performs the following Ada-specific optimiza¬ 
tions: 

• Elimination of redundant constraint checks. 

• Evaluation of all static subexpressions, even when evaluation is not 
required by the language; also evaluation of other compile-time con¬ 
stant expressions that may not be considered to be "static" expressions 
in the language (for example, expressions involving concatenation or 
attributes such as TTMAGE). 

• Elimination of dead code (for example, elimination of unreachable 
branches with compile-time constant selectors in if and case state¬ 
ments). 

• Bounds checking of arrays whose index expressions are static. 

• Elimination of redundant address evaluations. 

In cases where address evaluations are eliminated, as in 
A(I) := A(I) + 1; 

where the address of A(I) is evaluated only once, a special increment 
instruction is generated. Note that the result of this addition may be 
assigned to a temporary variable if a constraint check must be performed 
before A(I) is updated. 
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In addition, with matrix computations such as 

for I in 1 . . N loop 
for J in 1 .. M loop 
A(I,J) := SOME.VALUE; 
end loop; 
end loop; 

the address calculation for A(I,J) tends to be calculated each time using 
special VAX hardware addressing for this purpose (context indexing). 
Depending on various details, strength reduction may alternately be used. 
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Appendix A 


VAX Ada Packages 


VAX Ada provides the following packages: 

AUX_IO_EXCEPTIONS 

CALENDAR 

CONDITION-HANDLING 

CONTROL—C_INTERCEPTION 

DIRECT—IO 

DIRECT—MIXED—IO 

INDEXED—IO 

INDEXED—MIXED—IO 

IO—EXCEPTIONS 

MATH_LIB 

RELATIVE—IO 

RELATIVE—MIXED—IO 

RMS—ASYNCH—OPERATIONS 

SEQUENTIAL—IO 

SEQUENTIAL—MIXED—IO 

STANDARD 

STARLET 

SYSTEM 

TASKING-SERVICES 
TEXT—IO 

In addition, VAX Ada provides instantiations of some commonly used 
generic packages: 

FLOAT_MATH_LIB 
LONG_FLOAT_MATH_LIB 
LONG—LONG—FLOAT—MATH—LIB 
FLOAT—TEXT—IO 
INTEGER—TEXT—IO 
LONG—FLOAT—TEXT—IO 
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LONG—LONG—FLOAT—TEXT—IO 

SHORT_INTEGER_TEXT_IO 

SHORT_SHORT_INTEGER_TEXT_IO 

All of the packages and instantiations are briefly described in this ap¬ 
pendix. Complete specifications for those that are not presented in the 
VAX Ada Language Reference Manual are presented along with their de¬ 
scription. The two exceptions are the specifications of the packages 
STARLET (because of its size) and RMS_ASYNCH_OPERATIONS (be¬ 
cause it exists only to support the package TASKING—SERVICES). You 
can make a copy of STARLET'S specification by typing the command 

$ ACS EXTRACT SOURCE/LOG STARLET 


A.1 Package STANDARD 

Package STANDARD provides all the predefined types, operations, and 
exceptions defined by the language, as well as the additional VAX Ada 
types SHORT_INTEGER, SHORT_SHORT_INTEGER, LONG—FLOAT, 
and LONG—LONG—FLOAT. The package is discussed in Chapter 8 and 
its specification presented in Annex C of the VAX Ada Language Reference 
Manual. 


A.2 Package SYSTEM 

Package SYSTEM provides implementation-defined types, operations, con¬ 
stants and named numbers, some of which are required by the language 
standard, and some of which are provided by VAX Ada. The package is 
discussed in Chapter 13 and its specification presented in Appendix F of 
the VAX Ada Language Reference Manual. 


A.3 Package CALENDAR 

Package CALENDAR provides time-related types and operations. The 
package is discussed and its specification presented in Chapter 9 of the 
VAX Ada Language Reference Manual. 
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A.4 Input-Output Packages 


VAX Ada provides nine input-output packages and two input-output 
exceptions packages. Packages SEQUENTIAL—IO, DIRECT—IO, TEXT— 
IO, and IO—EXCEPTIONS are predefined by the language standard; 
packages RELATIVE_IO, INDEXED_IO, SEQUENTIAL_MIXED_IO, 
DIRECT_MIXED_IO, RELATIVE_MIXED_IO, INDEXED_MIXED_IO, 
and AUX_IO_EXCEPTIONS are predefined by VAX Ada. All of the nine 
input-output packages depend on the package IO_EXCEPTIONS; the 
four input-output packages for working with relative and indexed files 
also depend on the package AUX_IO_EXCEPTIONS. These packages are 
discussed in Chapter 2 of this manual. Their specifications and detailed 
explanations of their operations are given in Chapter 14 of the VAX Ada 
Language Reference Manual. 


A.5 Package STARLET 

Package STARLET provides the types, operations, constants, and so on 
that are needed to call VAX/VMS system service and Record Management 
Services (RMS) routines. Use of this package is described in Chapter 5 
of this manual; only the types it provides are presented here. Its 
complete specification is in the VAX Ada library of predefined units 
(ADA$PREDEFINED). STARLET depends on the packages SYSTEM and 
CONDITION-HANDLING. 

-- Ada parameter types and subtypes for VAX/VMS system 
-- service calls. 

-- Types defined in predefined STANDARD that are used 
-- as parameter types for VAX/VMS system service calls 
-- include BOOLEAN, INTEGER, SHORT.INTEGER, and STRING. 

-- Several types in predefined SYSTEM are used, 

-- including ADDRESS, AST_HANDLER, UNSIGNED.LONGWORD, 

-- and other unsigned types. 

-- Additional parameter types are defined below: 
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-- ACCESS_BIT_NAMES_TYPE 

-- Array of 32 elements in which each element is a string 
-- descriptor; each for the name of one of the 32 bits 
-- in an access mask. The ACCNAM parameter of the 
-- FORMAT_ACL system service is of this type. 

type ACCESS_BIT_NAMES_TYPE is 

array (0 .. 31) of SYSTEM.UNSIGNED_QUADWORD; 


— ACCESS_MODE_TYPE 

-- Hardware access mode. This can take four values: 
-- 0 specifies kernel mode; 1, executive mode; 

-- 2, supervisor mode; and 3, user mode. 

subtype ACCESS_MODE_TYPE is 

SYSTEM.UNSIGNED.WORD range 0 .. 3; 
ACCESS_M0DE_ZER0 : constant ACCESS_MODE_TYPE := 0; 


-- ADDRESS_RANGE_TYPE 

-- Array of addresses denoting a range of virtual 
-- addresses, which identify an area of memory. The 
-- first specifies the beginning address in the 
-- range; the second specifies the ending address 
-- in the range. 

type ADDRESS_RANGE_TYPE is 

array (0 .. 1) of SYSTEM.ADDRESS; 


-- ARG_LIST_TYPE 

-- Procedure argument list consisting of one or more 
-- longwords; the first longword contains an unsigned 
-- integer count of the number of successive, contiguous 
-- longwords, each of which is a parameter to be passed 
-- to a procedure by means of a VAX CALL instruction. 

subtype ARG_LIST_TYPE is SYSTEM.UNSIGNED_LONGWORD_ARRAY; 
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CHANNEL.TYPE 


-- Unsigned word integer that is an index to an I/O 
-- channel. 

subtype CHANNEL.TYPE is SYSTEM.UNSIGNED.WORD; 
CHANNEL.ZERO : constant CHANNEL.TYPE := 0; 


-- COND.VALUE.TYPE (CONDITION_HANDLING.COND_VALUE.TYPE) 


-- VAX/VMS condition value. (See package 
— CONDITION.HANDLING.) 

COND.VALUE.ZERO : constant 

CONDITION.HANDLING.COND.VALUE.TYPE := 0; 
COND.VALUE.l : constant 

CONDITION.HANDLING.COND.VALUE.TYPE := 1; 


-- CONTEXT.TYPE 

-- Unsigned longword that is used by a called procedure 
-- to maintain some context. 

subtype CONTEXT.TYPE is SYSTEM.UNSIGNED.LONGWORD; 


-- DATE.TIME.TYPE 

-- 64-bit unsigned, binary integer denoting a date and 
-- time as the number of elapsed 100-nanosecond units 
-- since 00:00 o'clock, November 17, 1858. 

subtype DATE.TIME.TYPE is SYSTEM.UNSIGNED.QUADWORD; 


-- DEVICE.NAME.TYPE 

-- Character string denoting the name of a device. It 
-- can be a logical name, but if it is, it must 
-- translate to a valid device name. 

subtype DEVICE.NAME.TYPE is STRING; 
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-- EF_CLUSTER_NAME_TYPE 

-- Character string denoting the name of an event flag 
-- cluster. It can be a logical name, but if it is, it 
-- must translate to a valid event flag cluster name. 

subtype EF_CLUSTER_NAME_TYPE is STRING; 


— EF_NUMBER_TYPE 

-- Unsigned longword integer denoting the number of an 

— event flag. 

subtype EF_NUMBER_TYPE is SYSTEM.UNSIGNED.WORD; 
EF_NUMBER_ZERO : constant EF_NUMBER_TYPE := 0; 


-- EXIT_HANDLER_BLOCK_TYPE 

-- Variable-length structure denoting an exit handler 
-- control block. The DESBLK parameter of the DCLEXH 
-- system service is of this subtype. 

subtype EXIT_HANDLER_BLOCK_TYPE is 
SYSTEM.UNSIGNED_L0NGW0RD_ARRAY; 


-- FAB_TYPE 

-- RMS file access block. Type definition is in STARLET. 


-- FILE_PR0TECTI0N_TYPE 

-- 16-bit file protection mask. The mask contains four 
-- 4-bit fields, each of which specifies the protection 
-- to be applied to file access attempts by one of the 
-- four categories of user. 

subtype FILE_PROTECTION_TYPE is SYSTEM.UNSIGNED.WORD; 
FILE_PR0TECTI0N_ZER0 : constant 
FILE_PROTECTI0N_TYPE := 0; 
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type FILE_PROTECTION_FLAGS_TYPE is 

record 

NOREAD : BOOLEAN;-- deny read access 
NOWRITE : BOOLEAN;— deny write access 
NOEXE : BOOLEAN;-- deny execution access 
NODEL : BOOLEAN;— deny delete access 

end record; 

pragma PACK (FILE_PROTECTION_FLAGS_TYPE); 


type FILE_PROTECTION_REC_TYPE is 

record 

SYS : FILE_PROTECTION_FLAGS_TYPE; 

OWN : FILE_PROTECTION_FLAGS_TYPE; 

GRP : FILE_PROTECTION_FLAGS_TYPE; 

WLD : FILE_PROTECTION_FLAGS_TYPE; 

end record; 

for FILE_PROTECTION_REC_TYPE use 

record 

SYS at 0 range 0 .. 3; 

OWN at 0 range 4 .. 7; 

GRP at 1 range 0 .. 3 ; 

WLD at 1 range 4 .. 7; 

end record; 

for FILE_PROTECTION_REC_TYPE'SIZE use 16; 


-- FUNCTION_CODE_TYPE 

-- Unsigned word specifying the operations a 
-- system service is to perform. The FUNC argument 
-- to the QIO system service is of this type. See 
-- also ITEM.LIST.TYPE. 

subtype FUNCTION_CODE_TYPE is SYSTEM.UNSIGNED.WORD; 
FUNCTION_CODE_ZERO : constant FUNCTION_CODE_TYPE := 0; 
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IOSB.TYPE 


-- Quadword record containing information returned by a 
-- system service that completes asynchronously. The 
-- information returned varies depending on the 
-- service. See QIO, GETDVI, and GETJPI 


type IOSB.TYPE is 

record 


STATUS : SYSTEM.UNSIGNED_WORD; 

COUNT : SYSTEM.UNSIGNED.WORD; 

DEV.INFO : SYSTEM.UNSIGNED_LONGWORD; 

end record; 


-- ITEM_LIST_TYPE 

-- Array that consists of one or more item 
-- descriptors and that is terminated by a longword 
-- containing 0. Each item descriptor is a 3-longword 
-- structure that contains four fields. The ITMLST 
-- parameter of the GETDVI system service is of this 
-- type. 

type ITEM_REC_TYPE is 

record 

-- Length of the buffer (in bytes) containing or 
-- receiving the information specified by 
-- ITEM.CODE; 

BUF_LEN : SYSTEM.UNSIGNED.WORD; 

-- Code indicating the operation to be performed. 

ITEM.CODE : SYSTEM.UNSIGNED.WORD; 
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-- Address of the buffer containing or receiving 
— the information specified by ITEM_C0DE. 

BUF.ADDRESS : SYSTEM.ADDRESS; 

-- Address of a word to receive the length of the 
-- information returned. 

RET_ADDRESS : SYSTEM.ADDRESS; 

end record; 

type ITEM_LIST_TYPE is 

array (NATURAL range <>) of ITEM_REC_TYPE; 


-- ITEM_LIST_2_TYPE 

-- Array of one or more item descriptors that is 
-- terminated by a longword containing 0. Each item 
-- descriptor is a 2-longword structure that contains 
-- three fields. The VALUELST parameter of the FILESCAN 
-- system service is of this subtype. 

subtype ITEM_LIST_2_TYPE is SYSTEM.UNSIGNED_LONGWORD_ARRAY; 


-- LOCK_VALUE_BLOCK_TYPE 

-- 16-byte block that the lock manager facility includes 
-- in a lock status block if the user requests it; the 
-- contents of the lock value block are user-defined 
-- and are not interpreted by the lock manager facility. 

subtype LOCK_VALUE_BLOCK_TYPE is 

SYSTEM.UNSIGNED_BYTE_ARRAY (1 .. 16); 


-- LOCK_ID_TYPE 

-- Unsigned longword integer denoting a lock identifier. 
-- This lock identifier is assigned by the lock manager 
-- facility to a lock when the lock is granted. 

subtype LOCK_ID_TYPE is SYSTEM.UNSIGNED_LONGWORD; 
L0CK_ID_ZER0 : constant LOCK_ID_TYPE := 0; 
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-- LOCK_STATUS_BLOCK_TYPE 

— Structure into which the lock manager facility writes 
-- status information about a lock. A lock status block 
-- always contains at least two longwords: the first word 
-- of the first longword contains a status code; the 
-- second word of the first longword is reserved to 
-- DIGITAL; and the second longword contains the lock 
-- identifier. In addition to the above fields, a lock 
-- status block may optionally include a 16-byte lock 
-- value block. 

type LOCK_STATUS_BLOCK_TYPE is 

record 

STATUS : CONDITION.HANDLING.COND_VALUE_TYPE; 

ID : LOCK_ID_TYPE; 

VALU : LOCK_VALUE_BLOCK_TYPE; 

end record; 


-- LOGICAL_NAME_TYPE 

-- Character string of from 1 to 255 characters that 
-- identifies a logical name or equivalence name 
-- to be manipulated by VAX/VMS logical name system 
-- services. 

subtype LOGICAL_NAME_TYPE is STRING; 


-- MASK_PRIVILEGES_TYPE 

-- Unsigned quadword wherein each individual bit denotes 
-- a process privilege. The PRVADR parameter of the 
-- CREPRC system service is of this subtype. 

subtype MASK_PRIVILEGES_TYPE is SYSTEM.BIT,ARRAY.64; 
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-- PAGE_PROTECTION_TYPE 


-- Unsigned longword specifying page protection to be 
— applied by the VAX hardware. The PROT parameter of 
-- the SETPRT system service is of this subtype. 


subtype PAGE_PROTECTION_TYPE is SYSTEM.UNSIGNED_LONGWORD; 


-- PROCESS.ID_TYPE 

-- Unsigned longword integer denoting a process 
-- identifier (PID). This process identifier is 
-- assigned by VMS to a process when the process 
-- is created. The PIDADR parameter of the DELPRC 
-- system service is of this subtype. 

subtype PROCESS.ID.TYPE is SYSTEM.UNSIGNED.LONGWORD; 


-- PROCESS.NAME.TYPE 

-- Character string that specifies the name of a process, 
subtype PROCESS.NAME.TYPE is STRING; 


-- RIGHTS.ID.TYPE 

-- Unsigned longword denoting a rights identifier, which 
-- identifies an interest group in the context of the 
-- VAX/VMS security environment. This rights identifier 
-- may consist of all or part of a user's User 
-- Identification Code (UIC). 

subtype RIGHTS.ID.TYPE is SYSTEM.UNSIGNED.LONGWORD; 
RIGHTS.ID.ZERO : constant RIGHTS.ID.TYPE := 0; 
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-- RIGHTS_HOLDER_TYPE 

-- Unsigned quadword specifying a user's access rights 
-- to a system object. The RACCESS component is a 
-- longword bitmask wherein each bit specifies an access 
-- right. The HOLDER parameter of the ADD_HOLDER system 
-- service is of this type. 

type RIGHTS_HOLDER_TYPE is 

record 

RIGHTS.ID : RIGHTS_ID_TYPE; 

RACCESS : SYSTEM.UNSIGNED.LONGWORD; 

end record; 


-- RAB_TYPE 

-- RMS record access block. Type definition is in 
-- STARLET. 


-- SECTION_ID_TYPE 

-- Unsigned quadword denoting a global section 
-- identifier. This identifier specifies the version 
-- of a global section and the criteria to be used in 
-- matching that global section. The IDENT parameter 
-- of the MGBLSC system service is of this subtype. 

subtype SECTION_ID_TYPE is SYSTEM.UNSIGNED.QUADWORD; 


-- SECTION_NAME_TYPE 

-- Character string denoting a global section name. 

-- This character string can be a logical name, but it 
-- must translate to a valid global section name. The 
-- GSDNAM parameter of the MGBLSC system service is of 
-- this subtype. 

subtype SECTION_NAME_TYPE is STRING; 
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-- SYSTEM_ACCESS_ID_TYPE 

-- Unsigned quadword that denotes a system 
-- identification value that is to be associated with 
-- a rights database. The SYSID parameter of the 
-- CREATE_RDB system service is of this subtype. 

subtype SYSTEM.ACCESS.ID.TYPE is 
SYSTEM.UNSIGNED.QUADWORD; 


— TIME.NAME.TYPE 

-- Character string specifying a time value in VAX/VMS 
-- format. The TIMBUF parameter of the ASCTIM system 
-- service is of this subtype. 

subtype TIME.NAME.TYPE is STRING; 


— UIC.TYPE 


-- Unsigned longword denoting a User Identification 
-- Code (UIC). 

subtype UIC.LONGWORD.TYPE is SYSTEM.UNSIGNED.LONGWORD; 
UIC.LONGWORD.ZERO : constant UIC.LONGWORD.TYPE := 0; 


-- USER.ARG.TYPE 

-- Unsigned longword denoting a user-defined argument. 
-- This longword is passed to a procedure as a 
-- parameter, but the contents of the longword are 
-- defined and interpreted by the user. The ASTPRM 
-- parameter of the QIO system service is of this 
-- subtype. 

subtype USER.ARG.TYPE is SYSTEM.UNSIGNED.LONGWORD; 
USER.ARG.ZERO : constant USER.ARG.TYPE := 0; 
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A.6 Package CONDITION—HANDLING 


Package CONDITION-HANDLING provides types and operations 
needed to evaluate the condition values returned by system routines. 
Its specification is as follows: 

with SYSTEM; use SYSTEM; 
package CONDITION_HANDLING is 

-- This package defines a VAX/VMS condition value 
-- type, functions for accessing components of a 
-- condition value, and interfaces to LIB$SIGNAL, 

— LIB$ST0P, and LIB$MATCH_COND. 

-- VAX/VMS system services return values of type 
-- COND_VALUE_TYPE. 

subtype COND_VALUE_TYPE is SYSTEM.UNSIGNED_LONGWORD; 

-- VAX/VMS severity codes are defined in STARLET as: 


STS_K_WARNING 

constant 

= 0 

STS_K_SUCCESS 

constant 

= 1 

STS_K_ERROR 

constant 

= 2 

STS_K_INF0 

constant 

= 3 

STS_K_SEVERE 

constant 

= 4 


-- Components of a condition value can be obtained via 
— the following functions. See Appendix C of the 
-- VAX Architecture Handbook or the section on condition 
-- handling in the VAX/VMS Run-Time Library Routines 
-- Reference Manual. The partial representation 
-- specification following each description indicates 
-- the portion of the condition value returned by each 
-- of the functions. 

SEVERITY 

Severity code: STS_K__WARNING, STS_K__SUCCESS, 
STS_K_ERROR, STS_K__INF0, or STS_K__SEVERE 

for SEVERITY at 0 range 0 .. 2; 


SUCCESS 

Is TRUE if low bit of severity is on. This 

occurs for a severity of STS_K_SUCCESS or 

STS_K_INFO. 

for SUCCESS at 0 range 0 .. 0; 
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COND_ID 

Identifies the conditions uniquely on a system- 
wide basis. 

for C0ND_ID at 0 range 3 .. 27; 


FAC.NO 

Identifies the software component generating the 
condition value. 

for FAC_NO at 0 range 16 .. 27; 

CUST_DEF 

Is TRUE for customer facilities and FALSE for 
DIGITAL facilities. 

for CUST.DEF at 0 range 27 .. 27; 


MSG_NO 

A status identification, that is, a description 
of the hardware exception that occurred or a 
software-defined value. 

for MSG_NO at 0 range 3 .. 15; 


FAC_SP 

Is TRUE for message numbers that are specific to 
a single facility and FALSE for systemwide 
message numbers. 

for FAC_SP at 0 range 15 .. 15; 

CODE 

Message number (without facility specific flag). 
for CODE at 0 range 3 .. 14; 

INHIB.MSG 

Is TRUE if the message should be inhibited on 
image exit and FALSE otherwise. 

for INHIB.MSG at 0 range 27 .. 27; 
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function SEVERITY (STATUS : COND_VALUE_TYPE) 
return UNSIGNED.LONGWORD; 
function SUCCESS (STATUS : COND_VALUE_TYPE) 
return BOOLEAN; 

function COND_ID (STATUS : COND_VALUE_TYPE) 
return UNSIGNED.LONGWORD; 
function FAC_N0 (STATUS : COND_VALUE_TYPE) 

return UNSIGNED_LONGWORD; 
function CUST_DEF (STATUS : COND_VALUE_TYPE) 
return BOOLEAN; 

function MSG_NO (STATUS : COND_VALUE_TYPE) 

return UNSIGNED.LONGWORD; 
function FAC_SP (STATUS : COND_VALUE_TYPE) 

return BOOLEAN; 

function CODE (STATUS : COND_VALUE_TYPE) 

return UNSIGNED_LONGWORD; 
function INHIB.MSG (STATUS : COND_VALUE_TYPE) 
return BOOLEAN; 

-- Some system services use status blocks (such as 
-- an I/O status block) which contain only the low 
-- order word of a condition value. Component- 
-- accessing functions are provided for SEVERITY, 

-- SUCCESS, and MSG_N0 for such status values, 
subtype WORD_COND_VALUE_TYPE is UNSIGNED_WORD; 

function SEVERITY(STATUS : WORD_COND_VALUE_TYPE) 
return UNSIGNED.LONGWORD; 
function SUCCESS (STATUS : WORD_COND_VALUE_TYPE) 
return BOOLEAN; 

function MSG_NO (STATUS : WORD_COND_VALUE_TYPE) 
return UNSIGNED.LONGWORD; 

-- Signaling errors 

-- The following is an interface to LIB$SIGNAL. This RTL 
-- routine can be used to signal a VAX/VMS condition value 
-- returned from a system service or RTL routine. The 
-- resulting exception can be handled in an Ada exception 
-- handler using OTHERS, N0N_ADA_ERR0R, or by importing 
-- a VAX condition as an Ada exception using 
-- IMPORT_EXCEPTION. 
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Usage: 


STATUS : COND_VALUE_TYPE; 


-- ASSIGN sets STATUS to a condition value 
ASSIGN (STATUS, ...); 

if not SUCCESS (STATUS) then SIGNAL (STATUS) end if; 
Parameters: 

CV 

Condition code value 
Notes: 

See the VAX/VMS Run-Time Library Routines 
Reference Manual. 


procedure SIGNAL (STATUS : in COND_VALUE_TYPE); 

-- The following is an interface routine to LIB$STOP. This 
-- RTL routine can be used to signal a VAX condition value 
-- returned from a system service or RTL routine. The 
-- resulting exception can be handled in an Ada exception 
-- handler using OTHERS, NON_ADA_ERROR, or by importing a 
-- VAX condition as an Ada exception using IMPORT_EXCEPTION. 

Usage: 

STATUS : COND_VALUE_TYPE; 


-- ASSIGN sets STATUS to a condition value 
ASSIGN (STATUS, ...); 

if not SUCCESS (STATUS) then STOP (STATUS) end if; 
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Parameters: 


CV 

Condition code value 


Notes: 

See the VAX/VMS Run-Time Library Routines 
Reference Manual. 


procedure STOP (STATUS : in COND_VALUE_TYPE); 

-- Matching condition values 

-- The following are interface routines to LIB$MATCH_COND. 
-- This RTL function can be used to determine if a 
-- given condition value matches a list of one or more 
-- condition values. 

Usage: 


INDEX 

:= MATCH.COND 

(CV 

COND.VALUE.TYPE, 



CVI 

COND_VALUE_TYPE) 

INDEX 

:= MATCH.COND 

(CV 

COND_VALUE_TYPE, 



CVI 

COND_VALUE_TYPE, 



CVn 

: COND.VALUE.TYPE) 


for n up to 8 


Parameters: 

CV 

Condition value to be matched against the list 
CVi 

Condition values, for i from 1 to 8, to be 
compared to CV 

Return value: 

INDEX : INTEGER 

0 if no match found 

i - 1 for a match between the first argument 
and the ith argument 
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Notes: 

The algorithm for matching condition values is 
described in the VAX/VMS Run-Time Library- 
Routines Reference Manual. 

function MATCH.COND ( 

COND_VALUE : COND_VALUE_TYPE; 

C0ND_VALUE_1 : COND_VALUE_TYPE) 
return INTEGER; 
function MATCH.COND ( 

COND_VALUE : COND_VALUE_TYPE; 

C0ND_VALUE_1 : COND_VALUE_TYPE; 

C0ND_VALUE_2 : COND_VALUE_TYPE) 
return INTEGER; 
function MATCH.COND ( 

COND.VALUE : COND_VALUE_TYPE; 

C0ND_VALUE_1 : COND_VALUE_TYPE; 

C0ND_VALUE_2 : COND_VALUE_TYPE; 

C0ND_VALUE_3 : COND_VALUE_TYPE) 
return INTEGER; 

function MATCH.COND ( 

COND.VALUE : COND.VALUE.TYPE; 

C0ND_VALUE_1 : COND_VALUE_TYPE; 

C0ND_VALUE_2 : COND_VALUE_TYPE; 

C0ND_VALUE_3 : COND_VALUE_TYPE; 

C0ND.VALUE.4 : COND_VALUE_TYPE) 
return INTEGER; 
function MATCH.COND ( 

COND.VALUE : COND.VALUE.TYPE; 

COND.VALUE.l : COND.VALUE.TYPE; 

C0ND.VALUE.2 : COND.VALUE.TYPE; 

C0ND.VALUE.3 : COND.VALUE.TYPE; 

C0ND.VALUE.4 : COND.VALUE.TYPE; 

C0ND.VALUE.5 : COND.VALUE.TYPE) 
return INTEGER; 

function MATCH.COND ( 

COND.VALUE : COND.VALUE.TYPE; 

COND.VALUE.l : COND.VALUE.TYPE; 

C0ND.VALUE.2 : COND.VALUE.TYPE; 

C0ND.VALUE.3 : COND.VALUE.TYPE; 

C0ND.VALUE.4 : COND.VALUE.TYPE; 

C0ND.VALUE.5 : COND.VALUE.TYPE; 

C0ND.VALUE.6 : COND.VALUE.TYPE) 
return INTEGER; 
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function MATCH.COND ( 
COND.VALUE : COND 
COND_VALUE_l : COND 
C0ND_VALUE_2 : COND 
C0ND_VALUE_3 : COND 
C0ND_VALUE_4 : COND 
C0ND_VALUE_5 : COND 
C0ND_VALUE_6 : COND 
C0ND_VALUE_7 : COND 
return INTEGER; 
function MATCH.COND ( 


COND_VALUE 
COND_VALUE_1 
C0ND_VALUE_2 
C0ND_VALUE_3 
C0ND_VALUE_4 
C0ND_VALUE_5 
C0ND_VALUE_6 
C0ND_VALUE_7 
C0ND_VALUE_8 
return INTEGER 


COND 

COND 

COND 

COND 

COND 

COND 

COND 

COND 

COND 


VALUE 

VALUE 

VALUE 

VALUE 

VALUE 

VALUE 

VALUE 

VALUE 


VALUE 

VALUE 

VALUE 

VALUE 

VALUE 

VALUE 

VALUE 

VALUE 

VALUE 


TYPE 

TYPE 

TYPE 

TYPE 

TYPE 

TYPE 

TYPE 

TYPE) 


TYPE 

TYPE 

TYPE 

TYPE 

TYPE 

TYPE 

TYPE 

TYPE 

TYPE) 


private 

-- implementation-dependent 
end CONDITION.HANDLING; 


A.7 Tasking Packages 

VAX Ada provides the following packages to make Ada tasking on 
VAX/VMS easier. They are discussed in Chapter 7 of this manual. 

• Package TASKING—SERVICES provides task-synchronous, process- 
asynchronous forms of the VAX/VMS system services SYS$BRKTHRU, 
SYSSENQ, SYS$GETDVI, SYS$GETJPI, SYS$GETLKI, SYS$GETSYI, 
SYS$QIO, SYS$SNDJBC, SYS$UPDSEC, and any VAX RMS record 

or block operation. It depends on the packages STARLET, SYSTEM, 
CONDITION-HANDLING, and RMS—ASYNCH—OPERATIONS. 

• Package RMS_ASYNCH—OPERATIONS provides supporting opera¬ 

tions for package TASKING—SERVICES; it depends on the packages 
STARLET, CONDITION-HANDLING, and SYSTEM. 

• Package CONTROL_C_INTERCEPTION establishes a VAX Ada 
CTRL/C handler when it is elaborated. 
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Because the package RMS_ASYNCH_OPERATIONS exists only to 

support the package TASKING—SERVICES, its specification is not given 
here. 


A.7.1 Package TASKING-SERVICES 

The specification of this package is as follows: 

with STARLET; use STARLET; 
with SYSTEM; use SYSTEM; 

with CONDITION_HANDLING; use CONDITION_HANDLING; 
with RMS_ASYNCH_OPERATIONS; use RMS_ASYNCH_OPERATIONS; 
package TASKING_SERVICES is 

-- DESCRIPTION: 

-- Certain VAX/VMS system services allow the calling routine 
-- to synchronize with the completion of the service. That 
-- is, after issuing (queuing) the system service call, the 
-- calling routine may continue executing until the service 
-- completes. Then, the routine can synchronize with the 
-- service via an event flag and/or an AST handler. 

-- If one of these services is called by a VAX Ada task in 
-- a program where time slicing has not been enabled, and 
-- event-flag synchronization has been chosen (for example, 
-- SYSSQIOW has been called), the process in which the 
-- calling task is executing will be suspended until the 
-- event flag is set. This effect may not be desired 
-- because suspension of the process causes all other 
-- executing tasks to be suspended, even if they are ready 
-- for execution. 

-- This package provides a convenient interface to VAX/VMS 
-- system services that have both synchronous and 
-- asynchronous forms (for example, SYSSQIOW and SYSSQIO). 

-- The package is designed for those situations in which 
-- you would like a particular task to wait for the 
-- completion of a system service, but do not want to 
-- prevent other tasks in your program from executing. 

-- Although pragma AST_ENTRY and attribute T'AST_ENTRY 
-- provide a more general way of achieving the same effect, 
-- they require more detailed programming. 
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-- The package provides an interface to the following VAX/VMS 
-- system services: 


System service 

SBRKTHRU 
$ENQ 
SGETDVI 
SGETJPI 
SGETLKI 
SGETSYI 
$QI0 
SSNDJBC 
SUPDSEC 
all RMS operations 


TASKING.SERVICES name 

TASK.BRKTHRUW 
TASK.ENQW 
TASK_GETDVIW 
TASK_GETJPIW 
TASK_GETLKIW 
TASK.GETSYIW 
TASK_QI0W 
TASK.SNDJBCW 
TASK_UPDSECW 
TASK_RMS_* 

(for example, 
TASK_RMS_GET) 


-- The signatures of the subprogram declarations generally 
-- correspond to those in STARLET, and use the same parameter 
-- types declared in STARLET. Refer to Chapter 5 of the VAX 
-- Ada Programmer's Run-Time Reference Manual for information 
-- on calling system services; the same considerations apply 
-- for both STARLET and TASKING.SERVICES. Differences from 
-- the declarations in STARLET are: 

1. The AST handler and AST parameter parameters are 
omitted because they are used to implement this 
package. 

2. In STARLET, a default value of 

type-name'NULL.PARAMETER is used for optional 
input arguments that are passed by reference or 
descriptor. In this package, multiple over- 
loadings are used to achieve the same effect. 

-- TASK.BRKTHRUW 

Write to terminal breakthrough and suspend the 
task until the system service is completed. 
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Parameters: 


efn = event flag to be set at completion 

msgbuf = address of message buffer descriptor 

sendto = address of send address descriptor 

sndtyp = value to describe sendto 

iosb = address of a quadword I/O status block 

carcon = carriage control 

flags = flags to modify broadcast 

reqid = broadcast class requestor id 

timout = address of timeout value 



procedure TASK.BRKTHRUW ( 

STATUS : out COND_VALUE_TYPE; 

EFN : in EF_NUMBER_TYPE := EF_NUMBER_ZERO; 

IGNORED : in ADDRESS := ADDRESS_ZERO; 

SENDTO : in STRING; 

SNDTYP : in UNSIGNED.LONGWORD := 0; 

IOSB : out I0SB_TYPE; 

CARCON : in UNSIGNED.LONGWORD := 32; 

FLAGS : in UNSIGNED.LONGWORD := 0; 

REQID : in UNSIGNED_LONGWORD := 0; 

TIMOUT : in UNSIGNED.LONGWORD := 0); 
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procedure TASK.BRKTHRUW ( 

STATUS : out COND_VALUE_TYPE; 
EFN : in EF_NUMBER_TYPE 
MSGBUF : in STRING; 

IGNORED : in ADDRESS 

SNDTYP : in UNSIGNED_LONGWORD 

IOSB : out I0SB_TYPE; 

CARCON : in UNSIGNED.LONGWORD 
FLAGS : in UNSIGNED_LONGWORD 
REQID : in UNSIGNED.LONGWORD 
TIMOUT : in UNSIGNED.LONGWORD 
procedure TASK.BRKTHRUW ( 

STATUS : out COND_VALUE_TYPE; 
EFN : in EF_NUMBER_TYPE 
SNDTYP : in UNSIGNED.LONGWORD 
IOSB : out IOSB.TYPE; 

CARCON : in UNSIGNED.LONGWORD 
FLAGS : in UNSIGNED.LONGWORD 
REQID : in UNSIGNED_LONGWORD 
TIMOUT : in UNSIGNED.LONGWORD 
procedure TASK_BRKTHRUW ( 

STATUS : out COND_VALUE_TYPE; 
EFN : in EF_NUMBER_TYPE 

MSGBUF : in STRING; 

SENDTO : in STRING; 

SNDTYP : in UNSIGNED.LONGWORD 
IOSB : in ADDRESS 
CARCON : in UNSIGNED.LONGWORD 
FLAGS : in UNSIGNED.LONGWORD 
REQID : in UNSIGNED.LONGWORD 
TIMOUT : in UNSIGNED.LONGWORD 
procedure TASK.BRKTHRUW ( 

STATUS : out COND_VALUE_TYPE; 
EFN : in EF_NUMBER_TYPE 
IGNORED : in ADDRESS 
SENDTO : in STRING; 

SNDTYP : in UNSIGNED.LONGWORD 
IOSB : in ADDRESS 
CARCON : in UNSIGNED.LONGWORD 
FLAGS : in UNSIGNED.LONGWORD 
REQID : in UNSIGNED.LONGWORD 
TIMOUT : in UNSIGNED.LONGWORD 


:= EF.NUMBER.ZERO; 

:= ADDRESS.ZERO; 

:= 0 ; 

:= 32; 

:= 0 ; 

:= 0 ; 

:= 0 ) ; 


:= EF.NUMBER.ZERO; 
:= 0 ; 

:= 32; 

:= 0 ; 

:= 0 ; 

:= 0 ) ; 


:= EF.NUMBER.ZERO; 


= 0 ; 

= ADDRESS.ZERO; 
= 32; 

= 0 ; 

= 0 ; 

= 0) ; 


:= EF.NUMBER.ZERO; 
:= ADDRESS.ZERO; 

:= 0 ; 

:= ADDRESS.ZERO; 

:= 32; 

:= 0 ; 

:= 0 ; 

:= 0 ) ; 
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procedure TASK_BRKTHRUW ( 


STATUS 

out COND_VALUE_TYPE; 


EFN 

in EF_NUMBER_TYPE 

= EF_NUMBER_ZERO; 

MSGBUF 

in STRING; 


IGNORED 

in ADDRESS 

= ADDRESS.ZERO; 

SNDTYP 

in UNSIGNED.LONGWORD 

= 0; 

IOSB 

in ADDRESS 

= ADDRESS_ZERO; 

CARCON 

in UNSIGNED.LONGWORD 

= 32; 

FLAGS 

in UNSIGNED.LONGWORD 

= 0; 

REQID 

in UNSIGNED.LONGWORD 

= 0; 

TIMOUT 

in UNSIGNED.LONGWORD 

= 0); 

procedure TASK_BRKTHRUW ( 


STATUS 

out COND_VALUE_TYPE; 


EFN 

in EF_NUMBER_TYPE 

= EF_NUMBER_ZERO; 

SNDTYP 

in UNSIGNED_LONGWORD 

= 0; 

IOSB 

in ADDRESS 

= ADDRESS_ZERO; 

CARCON 

in UNSIGNED_LONGWORD 

= 32; 

FLAGS 

in UNSIGNED_LONGWORD 

= 0; 

REQID 

in UNSIGNED.LONGWORD 

= 0; 

TIMOUT 

in UNSIGNED_LONGWORD 

= 0) ; 


-- TASK.ENQW 

Enqueue Lock Request and suspend the task until the 
lock is either granted or converted. 


Parameters: 


efn = event flag to be set at completion 

lkmode = type of lock mode requested. Modes are: 

LCK_K_NLMODE null lock 
LCK_K_CRMODE concurrent read 
LCK_K_CWMODE concurrent write 
LCK_K_PRMODE protected read 
LCK_K_PWMODE protected write 
LCK_K_EXMODE exclusive lock 

lksb = address of the lock status block 

flags = flags defining the characteristics of the 
lock. These are: 

LCK_M_NOQUEUE 

LCK_M_SYNCSTS 

LCK_M_SYSTEM 

LCK_M_VALBLK 

LCK_M_CONVERT 
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resnam = address of string descriptor of the resource 
name 

parid = lock ID of the parent lock 

blkast = address of entry mask of blocking AST 

routine; this AST handler must ignore its 
AST parameter 

acmode = access mode to be associated with the lock 

prot = optional additional arg for extension 

procedure TASK_ENQW ( 

STATUS : out COND_VALUE_TYPE; 

EFN : in EF_NUMBER_TYPE 
LKMODE : in UNSIGNED_LONGWORD; 

LKSB : out LOCK_STATUS_BLOCK_TYPE; 

FLAGS : in UNSIGNED.LONGWORD 
RESNAM : in STRING; 

PARID : in LOCK_ID_TYPE 
BLKAST : in AST.HANDLER 
ACMODE : in ACCESS_MODE_TYPE 
PROT : in ADDRESS 
procedure TASK_ENQW ( 

STATUS : out COND_VALUE_TYPE; 

EFN : in EF_NUMBER_TYPE 
LKMODE : in UNSIGNED.LONGWORD; 

LKSB : out LOCK_STATUS_BLOCK_TYPE; 

FLAGS : in UNSIGNED.LONGWORD 
PARID : in LOCK.ID.TYPE 
BLKAST : in AST.HANDLER 
ACMODE : in ACCESS.MODE.TYPE 
PROT : in ADDRESS 

— TASK.GETDVIW 

Get Device/Volume Information and suspend the task 
until the operation is complete. 

Parameters: 

efn = event flag to be set at completion 

chan = number of a channel assigned to the device 
or 0 if device is specified by the devnam 
parameter 


:= EF.NUMBER.ZERO; 


:= 0 ; 

:= LOCK.ID.ZERO; 

:= NO.AST.HANDLER; 

:= ACCESS.MODE.ZERO; 
:= ADDRESS.ZERO); 


:= EF.NUMBER.ZERO; 


= 0 ; 

= LOCK.ID.ZERO; 

= NO.AST.HANDLER; 

= ACCESS.MODE.ZERO; 
= ADDRESS.ZERO); 
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devnam = address of device name or logical name 
descriptor 

itmlst = address of a list of item descriptors 
iosb = address of a quadword I/O status block 


nullarg= reserved argument 
procedure TASK_GETDVIW ( 


STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF.NUMBER.ZERO; 

CHAN 

in 

CHANNEL.TYPE 

; = 

CHANNEL.ZERO; 

DEVNAM 

in 

DEVICE_NAME_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

IOSB.TYPE; 



NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_GETDVIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF.NUMBER.ZERO; 

CHAN 

in 

CHANNEL.TYPE 

: = 

CHANNEL.ZERO; 

ITMLST 

in 

ITEM.LIST.TYPE; 



IOSB 

out 

IOSB.TYPE; 



NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_GETDVIW ( 



STATUS 

out 

COND.VALUE.TYPE; 



EFN 

in 

EF.NUMBER.TYPE 

: = 

EF.NUMBER.ZERO; 

CHAN 

in 

CHANNEL.TYPE 

: = 

CHANNEL.ZERO; 

DEVNAM 

in 

DEVICE.NAME.TYPE; 



ITMLST 

in 

ITEM.LIST.TYPE; 



IOSB 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_GETDVIW ( 



STATUS 

out 

COND.VALUE.TYPE; 



EFN 

in 

EF.NUMBER.TYPE 

: = 

EF.NUMBER.ZERO; 

CHAN 

in 

CHANNEL.TYPE 

: = 

CHANNEL.ZERO; 

ITMLST 

in 

ITEM.LIST.TYPE; 



IOSB 

in 

ADDRESS 

; = 

ADDRESS.ZERO; 

NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 


-- TASK_GETJPIW 

Get Job/Process Information and suspend the task 
until the operation is complete. 


Parameters: 


efn = event flag to be set at completion 
pidadr = address of process identification 
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prcnam = address of process name string descriptor 
itmlst = address of a list of item descriptors 
iosb = address of a quadword I/O status block 


procedure TASK_GETJPIW ( 



STATUS 

out COND_VALUE_TYPE; 



EFN 

in EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO 

PIDADR 

in out PROCESS_ID_TYPE; 



PRCNAM 

in PROCESS_NAME_TYPE; 



ITMLST 

in ITEM_LIST_TYPE; 



IOSB 

out I0SB_TYPE); 



procedure TASK.GETJPIW ( 



STATUS 

out COND_VALUE_TYPE; 



EFN 

in EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

PIDADR 

in out PROCESS.ID_TYPE; 



ITMLST 

in ITEM_LIST_TYPE; 



IOSB 

out IOSB.TYPE); 



procedure TASK.GETJPIW ( 



STATUS 

out COND_VALUE_TYPE; 



EFN 

in EF_NUMBER_TYPE 

; = 

EF_NUMBER_ZERO; 

PIDADR 

in out PROCESS_ID_TYPE; 



PRCNAM 

in PROCESS_NAME_TYPE; 



ITMLST 

in ITEM_LIST_TYPE; 



IOSB 

in ADDRESS 

; = 

ADDRESS.ZERO); 

procedure TASK_GETJPIW ( 



STATUS 

out COND_VALUE_TYPE; 



EFN 

in EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

PIDADR 

in out PROCESS_ID_TYPE; 



ITMLST 

in ITEM_LIST_TYPE; 



IOSB 

in ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_GETJPIW ( 



STATUS 

out COND_VALUE_TYPE; 



EFN 

in EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

PIDADR 

in ADDRESS 

: = 

ADDRESS.ZERO; 

PRCNAM 

in PROCESS_NAME_TYPE; 



ITMLST 

in ITEM_LIST_TYPE; 



IOSB 

in ADDRESS 

; = 

ADDRESS.ZERO); 

procedure TASK_GETJPIW ( 



STATUS 

out COND_VALUE_TYPE; 



EFN 

in EF.NUMBER.TYPE 

; = 

EF_NUMBER_ZERO; 

PIDADR 

in ADDRESS 

: = 

ADDRESS.ZERO; 

ITMLST 

in ITEM_LIST_TYPE; 



IOSB 

in ADDRESS 

: = 

ADDRESS.ZERO); 
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procedure TASK.GETJPIW ( 


STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

:= EF_ 

_NUMBER_ZERO; 

PIDADR 

in 

ADDRESS 

:= ADDRESS.ZERO; 

PRCNAM 

in 

PROCESS_NAME_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

IOSB.TYPE); 



procedure TASK_GETJPIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

:= EF_ 

_NUMBER_ZERO; 

PIDADR 

in 

ADDRESS 

:= ADDRESS_ZERO; 

ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

I0SB_TYPE); 




-- TASK.GETLKIW 

Get Lock Information and suspend the task until the 
operation is complete. 


Parameters: 


efn 

lkidadr 

itmlst 

iosb 


= event flag to be set at completion 
= address of lock identification 
= address of a list of item descriptors 
= address of a quadword I/O status block 


reserved = reserved parameter 
procedure TASK.GETLKIW ( 


STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

; = 

EF_NUMBER_ZERO; 

LKIDADR 

in 

out LOCK_ID_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

IOSB.TYPE; 



RESERVED 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_GETLKIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

LKIDADR 

in 

out LOCK_ID_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

RESERVED 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK.GETLKIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

; = 

EF_NUMBER_ZERO; 

LKIDADR 

in 

ADDRESS 

; = 

ADDRESS.ZERO; 

ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

in 

ADDRESS 

: = 

ADDRESS_ZERO; 

RESERVED 

in 

ADDRESS 

: = 

ADDRESS_ZERO); 
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procedure TASK.GETLKIW ( 

STATUS : out COND_VALUE_TYPE; 
EFN : in EF_NUMBER_TYPE 
LKIDADR : in ADDRESS 
ITMLST : in ITEM_LIST_TYPE; 
IOSB : out IOSB.TYPE; 
RESERVED: in ADDRESS 

-- TASK.GETSYIW 


EF_NUMBER_ZERO; 
ADDRESS.ZERO; 


ADDRESS_ZERO); 


Get System-Wide Information and suspend the task until 
the operation is complete. 


Parameters: 

efn = event flag to be set at completion 

csidadr = address of cluster system identification 

nodename = address of node name string descriptor 

itmlst = address of a list of item descriptors 

iosb = address of a quadword I/O status block 

The second and third arguments in the SGETSYI 
argument list are not used; they are reserved 
for future use. 


procedure TASK.GETSYIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

:= EF_ 

.NUMBER.ZERO; 

CSIDADR 

in 

out PROCESS_ID_TYPE; 



NODENAME 

in 

PROCESS_NAME_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

IOSB.TYPE); 



procedure TASK.GETSYIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

:= EF. 

.NUMBER.ZERO; 

CSIDADR 

in 

out PROCESS.ID.TYPE; 



ITMLST 

in 

ITEM.LIST.TYPE; 



IOSB 

out 

IOSB.TYPE); 



procedure TASK.GETSYIW ( 



STATUS 

out 

COND.VALUE.TYPE; 



EFN 

in 

EF.NUMBER.TYPE 

: = EF_ 

.NUMBER.ZERO; 

CSIDADR 

in 

out PROCESS.ID.TYPE; 



NODENAME 

in 

PROCESS.NAME.TYPE; 



ITMLST 

in 

ITEM.LIST.TYPE; 



IOSB 

in 

ADDRESS 

:= ADDRESS_ZERO); 
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procedure TASK.GETSYIW ( 


STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

CSIDADR 

in out PROCESS_ID_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_GETSYIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

CSIDADR 

in 

ADDRESS 

; = 

ADDRESS.ZERO; 

NODENAME 

in 

PROCESS_NAME_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_GETSYIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

CSIDADR 

in 

ADDRESS 

; = 

ADDRESS.ZERO; 

ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

in 

ADDRESS 

; = 

ADDRESS.ZERO); 

procedure TASK_GETSYIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

; = 

EF.NUMBER.ZERO; 

CSIDADR 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

NODENAME 

in 

PROCESS_NAME_TYPE; 



ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

IOSB.TYPE); 



procedure TASK_GETSYIW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF.NUMBER.ZERO; 

CSIDADR 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

IOSB_TYPE); 




-- TASK.QIOW 


Queue I/O request and suspend the task until I/O 
is completed. 

Parameters: 

efn = number of event flag to set on completion 

chan = number of channel on which I/O is directed 
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func = function code specifying action to be 
performed 

iosb = address of quadword I/O status block to 
receive final completion status 

pi... = optional device- and function-specific 

parameters 


procedure TASK_QI0W ( 


STATUS 

out COND_VALUE_TYPE; 



EFN 

in EF_NUMBER_TYPE 

= EF.NUMBER.ZERO; 

CHAN 

in CHANNEL.TYPE; 



FUNC 

in FUNCTION.CODE.TYPE; 



IOSB 

out IOSB.TYPE; 



PI 

in UNSIGNED.LONGWORD 

= 0 


P2 

in UNSIGNED.LONGWORD 

= 0 


P3 

in UNSIGNED.LONGWORD 

= 0 


P4 

in UNSIGNED.LONGWORD 

= 0 


P5 

in UNSIGNED.LONGWORD 

= 0 


P6 

in UNSIGNED.LONGWORD 

= 0) ; 

procedure TASK_QI0W ( 



STATUS 

out COND.VALUE.TYPE; 



EFN 

in EF.NUMBER.TYPE 

= EF.NUMBER.ZERO; 

CHAN 

in CHANNEL.TYPE; 



FUNC 

in FUNCTION.CODE.TYPE; 



IOSB 

in ADDRESS 

= ADDRESS.ZERO; 

PI 

in UNSIGNED.LONGWORD 

= 0 


P2 

in UNSIGNED.LONGWORD 

= 0 


P3 

in UNSIGNED.LONGWORD 

= 0 


P4 

in UNSIGNED.LONGWORD 

= 0 


P5 

in UNSIGNED.LONGWORD 

= 0 


P6 

in UNSIGNED.LONGWORD 

= 0) ; 

-- TASK_SNDJBCW 




Send Message to Job Controller and suspend the 
task until the operation completes. 

Parameters: 

efn = event flag to be set when request completes 

func = code specifying function to be performed 

nullarg = reserved argument for similarity with 
Sgetxxx services 
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itmlst 


= address of a list of item descriptors for 
the operation 


iosb = address of a quadword status block to 
receive the final status 

procedure TASK.SNDJBCW ( 


STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO 

FUNC 

in 

FUNCTION_CODE_TYPE; 



NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

out 

IOSB.TYPE); 



procedure TASK_SNDJBCW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER.ZERO 

FUNC 

in 

FUNCTION_CODE_TYPE; 



NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

IOSB 

out 

IOSB.TYPE); 



procedure TASK_SNDJBCW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO 

FUNC 

in 

FUNCTION_CODE_TYPE; 



NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

ITMLST 

in 

ITEM_LIST_TYPE; 



IOSB 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 

procedure TASK_SNDJBCW ( 



STATUS 

out 

COND_VALUE_TYPE; 



EFN 

in 

EF_NUMBER_TYPE 

: = 

EF_NUMBER_ZERO; 

FUNC 

in 

FUNCTION_CODE_TYPE; 



NULLARG 

in 

ADDRESS 

: = 

ADDRESS.ZERO; 

IOSB 

in 

ADDRESS 

: = 

ADDRESS.ZERO); 


-- TASK.UPDSECW 

Update Section File on Disk and suspend the task 
until the operation is complete. 


Parameter: 

inadr = address of 2-longword array containing 
starting and ending addresses of the 
pages to be potentially written 

retadr = address of 2-longword array to receive 
addresses of the first and last page 
queued in the first I/O request 

acmode = access mode on behalf of which 
the service is performed 
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updflg = update indicator for read/write global 
sections 

0 -> write all read/write pages 
in the section 

1 -> write all pages modified by 
the caller 

efn = number of event flag to set when the section 
file is updated 

iosb = address of quadword I/O status block 
procedure TASK.UPDSECW ( 


STATUS 

out COND_VALUE_TYPE; 


IN ADR 

in ADDRESS_RANGE_TYPE; 


RETADR 

out ADDRESS_RANGE_TYPE; 


ACMODE 

in ACCESS_MODE_TYPE 

= ACCESS_MODE_ZERO; 

UPDFLG 

in BOOLEAN 

= FALSE; 

EFN 

in EF_NUMBER_TYPE 

= EF_NUMBER_ZERO; 

IOSB 

out IOSB.TYPE); 


procedure TASK_UPDSECW ( 


STATUS 

out COND_VALUE_TYPE; 


IN ADR 

in ADDRESS_RANGE_TYPE; 


RETADR 

out ADDRESS_RANGE_TYPE; 


ACMODE 

in ACCESS.MODE.TYPE 

= ACCESS_MODE_ZERO; 

UPDFLG 

in BOOLEAN 

= FALSE; 

EFN 

in EF_NUMBER_TYPE 

= EF_NUMBER_ZERO; 

IOSB 

in ADDRESS 

= ADDRESS.ZERO); 

procedure TASK_UPDSECW ( 


STATUS 

out COND_VALUE_TYPE; 


IN ADR 

in ADDRESS_RANGE_TYPE; 


RETADR 

in ADDRESS 

= ADDRESS.ZERO; 

ACMODE 

in ACCESS_MODE_TYPE 

= ACCESS_MODE_ZERO; 

UPDFLG 

in BOOLEAN 

= FALSE; 

EFN 

in EF_NUMBER_TYPE 

= EF_NUMBER_ZERO; 

IOSB 

in ADDRESS 

= ADDRESS.ZERO); 

procedure TASK_UPDSECW ( 


STATUS 

out COND_VALUE_TYPE; 


IN ADR 

in ADDRESS_RANGE_TYPE; 


RETADR 

in ADDRESS 

= ADDRESS.ZERO; 

ACMODE 

in ACCESS_MODE_TYPE 

= ACCESS_MODE_ZERO; 

UPDFLG 

in BOOLEAN 

= FALSE; 

EFN 

in EF_NUMBER_TYPE 

= EF_NUMBER.ZERO; 

IOSB 

out IOSB.TYPE); 



-- TASK_RMS_CLOSE 


Close File. This is a renaming of STARLET.CLOSE. 
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Parameter: 


fab = address of fab 

procedure TASK_RMS_CLOSE ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB_TYPE) renames STARLET.CLOSE; 

-- TASK_RMS_CONNECT 

Connect File 

Parameters: 

rab = address of rab 

procedure TASK_RMS_CONNECT is 

new RMS_ASYNCH_OPERATION (STARLET.CONNECT); 

-- TASK_RMS_CREATE 

Create File. This is a renaming of STARLET.CLOSE. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_CREATE ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB.TYPE) renames STARLET.CREATE; 

-- TASK_RMS_DELETE 

Delete Record 

Parameters: 

rab = address of rab 

procedure TASK_RMS_DELETE is 

new RMS_ASYNCH_OPERATION (STARLET.DELETE); 

-- TASK_RMS_DISCONNECT 

Disconnect Record Stream 

Parameters: 

rab = address of rab 

procedure TASK_RMS_DISCONNECT is 

new RMS_ASYNCH_OPERATION (STARLET.DISCONNECT); 
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TASK_RMS_DISPLAY 


Display File. This is a renaming of STARLET.DISPLAY. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_DISPLAY ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB.TYPE) renames STARLET.DISPLAY; 

-- TASK_RMS_ENTER 

Enter File. This is a renaming of STARLET.ENTER. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_ENTER ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB.TYPE) renames STARLET.ENTER; 

-- TASK_RMS_ERASE 

Erase File. This is a renaming of STARLET.ERASE. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_ERASE ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB.TYPE) renames STARLET.ERASE; 

— TASK.RMS.EXTEND 

Extend File. This is a renaming of STARLET.EXTEND. 

Parameters: 

fab = address of fab 

procedure TASK.RMS.EXTEND ( 

STATUS : out COND.VALUE.TYPE; 

FAB : in out FAB.TYPE) renames STARLET.EXTEND; 
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-- TASK_RMS_FIND 

Find Record in File. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_FIND is 

new RMS_ASYNCH_OPERATION (STARLET.FIND); 

-- TASK_RMS_FLUSH 

Flush Record. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_FLUSH is 

new RMS_ASYNCH_OPERATION (STARLET.FLUSH); 

-- TASK_RMS_FREE 

Free Record. 

Parameters: 

rab = address of fab 

procedure TASK_RMS_FREE is 

new RMS_ASYNCH_OPERATION (STARLET.FREE); 

-- TASK_RMS_GET 

Get Record from File. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_GET is 

new RMS_ASYNCH_OPERATION (STARLET.GET); 
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TASK_RMS_NXTVOL 


Go to Next Volume. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_NXTVOL is 

new RMS_ASYNCH_OPERATION (STARLET.NXTVOL); 

-- TASK_RMS_DPEN 

Open File. This is a renaming of STARLET.OPEN. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_OPEN ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB.TYPE) renames STARLET.OPEN; 

-- TASK_RMS_PARSE 

Parse File Name. This is a renaming of STARLET.PARSE. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_PARSE ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB.TYPE) renames STARLET.PARSE; 

-- TASK_RMS_PUT 

Put Record to File. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_PUT is 

new RMS_ASYNCH_OPERATION (STARLET.PUT); 
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TASK_RMS_READ 


Read Block from File. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_READ is 

new RMS_ASYNCH_OPERATION (STARLET.READ); 

-- TASK_RMS_RELEASE 

Release Record. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_RELEASE is 

new RMS_ASYNCH_OPERATION (STARLET.RELEASE); 

-- TASK_RMS_REMOVE 

Remove File. This is a renaming of STARLET.REMOVE. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_REMOVE ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB.TYPE) renames STARLET.REMOVE; 

-- TASK_RMS_RENAME 

Rename File. This is a renaming of STARLET.RENAME. 
Parameters: 

oldfab = address of oldfab 

err = address of user error completion routine 

sue = address of user success completion routine 

newfab = address of new fab 
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procedure TASK_RMS_RENAME ( 

STATUS : out COND_VALUE_TYPE; 

OLDFAB : in out FAB.TYPE; 

ERR : in AST.HANDLER 
SUC : in AST.HANDLER 
NEWFAB : in out FAB_TYPE) renames 

-- TASK_RMS_REWIND 

Rewind File. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_REWIND is 

new RMS_ASYNCH_OPERATION (STARLET.REWIND); 

-- TASK_RMS_SEARCH 

Search for File Name. This is a renaming of 
STARLET.SEARCH. 

Parameters: 

fab = address of fab 

procedure TASK_RMS_SEARCH ( 

STATUS : out COND_VALUE_TYPE; 

FAB : in out FAB_TYPE) renames STARLET.SEARCH; 

-- TASK_RMS_SPACE 

Space to Record in File. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_SPACE is 

new RMS_ASYNCH_OPERATION (STARLET.SPACE); 

-- TASK_RMS_TRUNCATE 

Truncate Record. 


:= NO_AST_HANDLER; 
:= NO_AST_HANDLER; 
STARLET.RENAME; 


Parameters: 

rab = address of rab 

procedure TASK_RMS_TRUNCATE is 

new RMS_ASYNCH_OPERATION (STARLET.TRUNCATE); 
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TASK_RMS_UPDATE 


Update Record. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_UPDATE is 

new RMS_ASYNCH_OPERATION (STARLET.UPDATE); 

-- TASK_RMS_WAIT 

Wait on File. This is a renaming of STARLET.WAIT. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_WAIT ( 

STATUS : out COND_VALUE_TYPE; 

RAB : in out RAB.TYPE) renames STARLET.WAIT; 

-- TASK_RMS_WRITE 

Write Block to File. 

Parameters: 

rab = address of rab 

procedure TASK_RMS_WRITE is 

new RMS_ASYNCH_OPERATION (STARLET.WRITE); 


private 

-- implementation-dependent 
end TASKING.SERVICES; 
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A.7.2 Package CONTROL_C_INTERCEPTIOiy 

The specification of this package is as follows: 

package CONTROL_C_INTERCEPTION is 

-- This package establishes a CTRL/C handler 
-- when it is elaborated. 

-- If your tasking program fails to stop when you type 
-- ~Y EXIT, or fails to invoke DEBUG when you type 
-- ~Y DEBUG, WITHing this package can cure the problem. 

-- WITH the package and elaborate it PRIOR to creating 
-- tasks in the program. 

-- Example: 

WITH CONTROL_C_INTERCEPTION; 

pragma ELABORATE(CONTROL_C_INTERCEPTION); 

procedure MY_MAIN_PROGRAM is ... 

-- Then, if CTRL/Y does not work as a way to invoke 
-- the debugger or exit, type CTRL/C. This will invoke 
-- the VAX Ada CTRL/C interceptor, which will give you 
-- most of the same options that CTRL/Y would. NOTE: other 
-- CTRL/C handlers that might be present in the program 
-- will also be able to execute (provided they are also 
-- "outband" AST handlers), either before or after 
-- the VAX Ada CTRL/C interceptor gives its prompt. 

-- CAUTION: 

-- Use of this package can override the intentions of 
-- the DCL command SET N0C0NTR0L_Y. It allows a user to 
-- type CTRL/C and get the same degree of control over 
-- the program. Hence, any Ada program that uses this 
-- package should NOT be used in "captive" command files 
-- (command files that prevent a user from gaining 
-- control by typing CTRL/Y). 

end; 
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A.rf Package MATH_LIB 


Package MATH—LIB provides a set of operations and exceptions that 
correspond to some of the VAX Run-Time Library Mathematical Library 
routines and conditions. This package is discussed in Chapter 5 of this 
manual, and its specification is as follows: 

generic 

type REAL is digits <>; 
package MATH_LIB is 

-- This is an interface package to the VAX/VMS RTL 
-- Mathematical Library routines. Details on the 
-- routines can be found in the VAX/VMS Run-Time 
-- Library Routines Reference Manual. 

-- (See MTH$ routines.) 

-- Square root 

function SQRT (A : REAL) return REAL; 

-- Natural logarithm - log base e (A) 

function LOG (A : REAL) return REAL; 

-- Common logarithm - log base 10 (A) 

function L0G10 (A : REAL) return REAL; 

-- Base 2 logarithm - log base 2 (A) *** not in FORTRAN 

function L0G2 (A : REAL) return REAL; 

-- Exponential 

function EXP (A : REAL) return REAL; 

— Sine, cosine, and tangent of an angle given in radians 

function SIN (A : REAL) return REAL; 

function COS (A : REAL) return REAL; 

function TAN (A : REAL) return REAL; 

-- Arc sine, arc cosine, and arc tangent - return an angle 
-- expressed in radians 


function 

ASIN 

(A 

REAL) 

return 

REAL; 

function 

ACOS 

(A 

REAL) 

return 

REAL; 

function 

ATAN 

(A 

REAL) 

return 

REAL; 
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-- Arc tangent with two parameters - Arc Tan (A1/A2) 

-- - returns an angle expressed in radians 

function ATAN2 (A1, A2 : REAL) return REAL; 

-- Hyperbolic sine, cosine, and tangent of an angle in 
-- radians 


function 

SINH 

(A 

REAL) 

return 

REAL 

function 

COSH 

(A 

REAL) 

return 

REAL 

function 

TANH 

(A 

REAL) 

return 

REAL 


-- Trigonometric functions for angles expressed in degrees 


function SIND 
function COSD 
function TAND 
function ASIND 
function ACOSD 
function ATAND 
function ATAN2D 


(A : REAL) return REAL; 

(A : REAL) return REAL; 

(A : REAL) return REAL; 

(A : REAL) return REAL; 

(A : REAL) return REAL; 

(A : REAL) return REAL; 

(Al, A2 : REAL) return REAL; 


-- ATAN2D is the FORTRAN spelling of the name of 
-- this function; it corresponds to the RTL 
-- routine MTH$ATAND2 


-- Exceptions: The following exceptions are raised by 
-- various RTL math library routines. See the VAX/VMS 
-- Run-Time Library Routines Reference Manual for 
-- details. 


ROPRAND 

INVARGMAT 

FLOOVEMAT 

FLOUNDMAT : 

LOGZERNEG : 
SQUROONEG : 


: exception; -- Reserved operand fault 

: exception; -- Invalid argument 

: exception; -- Floating point overflow in 

-- Math Library 

exception; -- Floating point underflow in 
-- Math Library 

exception; -- Logarithm of zero or negative value 
exception; -- Square root of a negative number 


private 

implementation-dependent 
end MATH.LIB; 
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A.9 Predefined Instantiations for TEXT—IO and MATH—LIB 
Operations 

For convenience, and for the purpose of saving compilation time and ob¬ 
ject code space, VAX Ada predefines the instantiations of some commonly 
used generic packages: 


Unit Name 

Instantiation of 

For Type 

INTEGER—TEXT—IO 

TEXT—IO.INTEGER—IO 

INTEGER 

SHORT—INTEGER—TEXT—IO 

TEXT—IO.INTEGER_IO 

SHORT-INTEGER 

SHORT_SHORT_INTEGER_ 

TEXT—IO 

TEXT—IO.INTEGER_IO 

SHORT_SHORT_INTEGER 

FLOAT—TEXT—IO 

TEXT—IO.FLOAT—IO 

FLOAT 

LONG—FLOAT—TEXT—IO 

TEXT—IO.FLOAT—IO 

LONG_FLOAT 

LONG—LONG—FLOAT—TEXT—IO 

TEXT—IO.FLOAT—IO 

LONG_LONG_FLOAT 

FLOAT_MATH_LIB 

MATH_LIB 

FLOAT 

LONG_FLOAT_MATH_LIB 

MATH_LIB 

LONG_FLOAT 

LONG—LONG—FLOAT—MATH—LIB 

MATH_LIB 

LONG_LONG_FLOAT 


The representation used for LONG_FLOAT in these packages is 
G_floating. Thus, in order to use LONG_FLOAT_IO and LONG— 
FLOAT—MATH—LIB, you must either be sure that the G—floating repre¬ 
sentation for LONG—FLOAT is in effect (G—floating is the default, and 
is established whenever a compilation library is created or reinitialized), 
or you must change the representation with pragma LONG—FLOAT 
(the alternative choice is D_floating), and copy and recompile the units 
LONG—FLOAT—IO and LONG—FLOAT—MATH—LIB. Any use of pragma 
LONG—FLOAT implies a recompilation of the predefined STANDARD 
environment. Section 3.5.7a of the VAX Ada Language Reference Manual 
describes pragma LONG—FLOAT in more detail. See also Developing Ada 
Programs on VAX/VMS for a discussion of using ACS commands to change 
the representation of LONG—FLOAT, as well as for a discussion of the 
implied recompilation of the predefined STANDARD environment. 

Use of the predefined instantiations for TEXT—IO.INTEGER—IO and 
TEXT—IO.FLOAT—IO is discussed in Chapter 2 of this manual; use of the 
predefined instantiations of MATH—LIB is discussed in Chapter 5. 
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Abort statement • 7-22 

synchronous implementation of *7-22 
Access objects 

default alignment of *3-26 
Access types 

allocation of collection for* 3-17 
length representation clauses with *3-16 
packing *3-19 

passing as parameters with 

DESCRIPTOR mechanism option* 
4-20 

passing parameters of *4-7, 4-10 
representation of *3-16 
returning as function results *4-12 
ACCESS_BIT_NAMES_TYPE • A-3 
ACCESS_MODE_TYPE • A-3 
ACOS* A-43 
ACOSD • A-43 
ADA$_EXCCOP 

condition value marking copied signal 
arguments in an exception • 6-6 
ADA$_EXCCOPLOS 

condition value marking copied and 
modified signal arguments in an 
exception • 6-6 

ADA$INPUT logical name *2-7, 2-73 
ADA$OUTPUT logical name *2-7, 2-73 
ADDRESS attribute • 8-3 

causing locally volatile parameter or 
variable • 8-3 

using to pass Ada subprogram as 

parameter to system routine* 5-18 
$ADDRESS program section *3-29 
ADDRESS type *8-3 
Address types 
packing *3-19 


Address types (cont'd.) 

passing as parameters with VALUE 
mechanism option *4-19 
passing parameters of*4-7, 4-11 
representation of *3-18 
returning as function results *4-12 
ADDRESS_RANGE_TYPE • A-3 
ADDRESS_ZERO *4-19 

as default expression for optional 
parameter *5-10 
Area control block 

for returning array type function results • 
4-12 

using to return record type function 
result *4-14 
ARG__LIST_TYPE • A-3 
Argument list *4-1, 4-5 

passed between languages and system 
service routines *5-7 
Argument pointer (AP)*4-5 
Array objects 

default alignment of *3-26 
storage for* 3-12 
Array types 

default alignment of components in* 

3- 13 

packable • 4-9 
packing *3-19 

passing as parameters with 

DESCRIPTOR mechanism option* 

4- 20 

passing parameters of *4-9 
representation of *3-12 
returning as function results *4-12 
ASIN* A-43 
ASIND* A-43 
AST reentrancy • 7-26 
AST—ENTRY attribute • 7-35 
AST_ENTRY pragma *7-35 
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ASTs (Asynchronous System Traps) - 7-32, 
7-35 

delivered to completed or abnormal 
tasks • 7-38 

examples of handling • 7-39 
handling from tasks *7-37 
storage allocated for* 7-38 
ATAN* A-43 
ATAN2 • A-43 
ATAN2D* A-43 
ATAND* A-43 

AUX_IO_EXCEPTIONS package • 2-74, A-2 
exceptions predefined in • 6-5 

B 


BASIC 

sharing common blocks with • 3-34 
Bit array *4-9 
Bit string *4-9 
Bit strings 

passing as parameters with VALUE 
mechanism option *4-19 

BLISS 

exporting and importing objects from • 
3-30 

sharing variables with *3-34 
Blocks 

exception handlers for *6-2 
stack frames for *6-2 
BOOLEAN objects 

default alignment of *3-26 
BOOLEAN type 

forcing 1-bit representation of *3-2 
packing *3-19 
Buffers 

control of terminal text file *2-67 
flushing of text file *2-67 
Busy waiting 

avoiding during task call to 
SYS$SET AST • 7-33 
avoiding to avoid AST deadlock • 7-39 

c 


c 

sharing variables with • 3-34 
CALENDAR package* A-2 
Call frame • 4-1, 4-5 
Call stack • 4-1 


CALLABLE attribute 

value of during task AST handling • 7-38 
CALLG instruction • 4-2 
CALLS instruction • 4-2 
Carriage control 

FORTRAN control characters for *2-71 
options for Ada text files *2-68 

CHANNEI_TYPE • A-3 

CHARACTER objects 

default alignment of *3-26 
CHARACTER type 

representation of *3-19 
CHF (VAX Condition Handling Facility) 
summary of exception-handling 
implementation • 6-3 
used to implement exception handling* 
6-1 

CLOSE procedure 

FORM parameter • 2-9 
CODE* A-14 

optional parameter to EXPORT— 
EXCEPTION pragma *6-12 
optional parameter to IMPORT— 
EXCEPTION pragma *6-10 
SCODE program section *3-29 
Collection 

allocation of for access type *3-17 
COND-ID* A-14 

COND_VALUE_TYPE* A-3, A-14 
Condition codes 

see Conditions (VAX) 

VAX Ada package for *6-19 
Condition handlers 

calling fault handlers from *6-19 
general VAX Ada • 6-3 
Condition handling 

see Exception handling 
Condition values 

see also Exceptions, Exception handling 
CONDITION-HANDLING package *5-1, 

6-19, A-13 

example of using MATCH—COND 
function • 5-25 

provision of interface to LIB$MATCH_ 
COND *5-23 

using to test status values *5-23 
Conditions 

conversion of to noncontinuable 
exceptions *6-13 

matching of with Ada exceptions • 6-6 
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Conditions (cont'd.) 

noncontinuable execution of • 6-13 
not caught by exception handlers • 6-14 
propagated to and handled by an Ada 
frame • 6-14 

using VAX Ada packages to determine 
matching of • 6-19 
Conditions (VAX) 

equivalent Ada predefined exceptions 
for • 6-7 

Conditions values 

giving to Ada exceptions • 6-10 
$CONSTANT program section • 3-29 
Constrainedness bits • 4-10 
CONSTRAINT_ERROR 
implementation of *6-2 
raised during parameter passing • 4-8 
raised when passing parameters • 4-8, 

4- 19, 4-23, 4-24, 4-25 
CONTEXT_TYPE • A-3 
CONTINUE command 

entering after CTRL/Y in tasking 
program • 7-23 
Control blocks 

declarations of types for in package 
STARLET *5-12 
example of using RMS • 5-15 
initialization constants for in STARLET* 

5- 13 

CONTROI_C—INTERCEPTION package* 

7-23, A-20 

Copy-in/copy-back semantics • 4-7 

for passing access type parameters* 
4-10 

for passing address type parameters* 
4-1 1 

for passing scalar parameters • 4-8 
for passing scalar, access, and address 
type parameters* 4-7 
COS* A-43 
COSD • A-43 
COSH* A-43 

CREATE procedure *2-2, 2-29, 2-30 
FILE parameter • 2-5 
FORM parameter • 2-2 
FORM parameter • 2-5 
MODE parameter • 2-31 
NAME parameter • 2-5 
CTRL/C 

interception with AST entry *7-41 


CTRL/Y 

interrupting tasks with *7-23 
CUST_DEF • A-14 

D 


D_FLOAT 

representation of *3-3 
storage size of *3-3 
D_floating representation • 3-9 
$DATA program section • 3-29 
Data types 
see Types 

DATE_TIME_TYPE • A-3 
Deadlock 

see Task deadlock 
DEBUG command 

entering after CTRL/Y in tasking 
program • 7-23 
Delay statement 

avoiding during task call to 
SYS$SETAST *7-33 
avoiding to avoid AST deadlock • 7-39 
Descriptor classes 

explanation of for VAX Ada • 4-20 
Descriptor mechanism • 4-7 

passing array type parameters by *4-9 
DESCRIPTOR mechanism option • 4-20 
descriptor data types used with • 4-25 
in import pragmas *4-18 
type requirements for descriptor classes 
for *4-22 

valid class names for *4-22 
Descriptors 

default used by VAX Ada for passing 
array type parameters* 4-9 
returning function results with *4-13 
using to pass parameters to exported 
Ada subprograms • 4-15 
DEVICE_NAME_TYPE • A-3 
DIRECT—IO 

default file attributes provided by *2-40 
DIRECT_IO package *2-2, 2-3, 2-33, A-2 
DIRECT_MIXED_IO package *2-2, 2-3, 
2-33, A-2 

default file attributes provided by *2-40 
example of using • 2-42 
Discrete types 

passing as parameters with VALUE 
mechanism option *4-19 
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DSC$K_CLASS_A • 4-9, 4-13 
DSC$K_CLASS_S • 4-15 
DSC$K_CLASS_SB • 4-9, 4-13, 4-15 
DSC$K_CLASS_UBA • 4-9, 4-13 
DSC$K_CLASS_UBS*4-15 
DSC$K_CLASS_UBSB • 4-9, 4-13, 4-15 
Dynamic memory 

use of to allocate storage • 8-2 

1 


EDIT/FDL Utility 

using to optimize external files *2-16 
EF_CLUSTER_NAME_TYPE • A-3 
EF_NUMBER_TYPE • A-3 
END—ERROR 

raised during terminal input-output • 2-63 
Enumeration literals 

default range of codes for • 3-2 
Enumeration types 

achieving unsigned representation of* 
3-2 

declaring signed integer codes for *3-21 
integer codes for *3-2 
packing *3-19 
passing parameters of *4-8 
representation of *3-2 
returning as function results *4-12 
Equivalence strings 

for process permanent files *2-8 
pairing with logical names *2-6 
Exception handler 
search for* 6-1 
Exception handlers 

general VAX Ada run-time *6-2 
invoking, in CHF terms *6-3 
unwinding to • 6-2 
use of others in *6- 14 
VAX Ada run-time *6-2 
VAX/VMS default *6-2, 7-20 
Exception handling • 6-1 
in non-Ada code • 6-6 
Exceptions 

Ada format *6-3, 6-4, 6-5, 6-12 
associating VAX conditions with *6-10 
avoiding propagation of unhandled • 

7-33 

avoiding propagation of unhandled to 
avoid AST deadlock* 7-39 
consequences of noncontinuable 
execution of • 6-13 


Exceptions (cont'd.) 

copying of signal arguments for *6-4, 
7-20 

copying signal arguments for *6-6 
effect on text file buffers • 2-67 
effects of propagating to tasks *7-20 
example of handling in mixed-language 
environment *6-15 

exporting to other languages as VAX 
conditions *6-12 

information lost during signal argument 
copying • 6-6 

interaction with tasking *6-19 
matching of imported *6-7 
matching of user-defined • 6-7 
matching of with VAX conditions • 6-6 
matching signal arguments of in non- 
Ada routine *6-12 
matching VAX conditions with *6-7 
mechanism argument vectors for *6-1 
naming and encoding *6-4 
noncontinuable execution of *6-4, 6-13 
predefined • 6-4, 6-5, 6-7 
propagation of outside the frame of a 
main program *7-20 
raising • 6-1 

raising at point of task rendezvous • 6-4 
raising imported • 6-10 
raising, in CHF terms *6-3 
re-raising • 6-4, 6-14 
re-raising, in CHF terms *6-3 
run-time checks that underlie• 6-7, 6-8 
signal argument vectors for *6-1 
suppressing checks that raise *6-7 
user-defined • 6-5, 6-6 
VAX condition equivalents for 
predefined • 6-7 

VAX condition values for predefined* 
6-1 

VAX condition values for user-defined* 
6-1 

VMS format *6-3, 6-4, 6-6, 6-12 
EXISTENCE_ERROR 

raised when reading Ada relative files* 
2-45 

EXIT command 

entering after CTRL/Y in tasking 
program • 7-23 

EXIT_HANDLER_BL0CK_TYPE • A-3 
EXP* A-43 
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Export pragmas *4-14 
EXPORT_EXCEPTION pragma •6-10. 6-12 
and N0N_ADA_ERR0R *6-19 
examples of using *6-13 
syntax of • 6-12 

use of to give user-defined exceptions 
VMS format • 6-6 

using to associate an Ada exception 
with a VAX condition* 6-12 
EXP0RT_0BJECT pragma • 3-30 
EXPORT_PROCEDURE pragma *4-14 
External files 
see also Files 

relationship to file objects *2-2 
specifying attributes of *2-9 

F 


F_FL0AT 

representation of *3-3 
storage size of *3-3 
F_floating representation • 3-7 
FAB (file access block) 

record type declared for in package 
STARLET *5-12 
FAB—TYPE • A-3 
FAC_N0* A-14 
FAC—SP • A-14 
FAO signal arguments 

matching of in non-Ada code *6-13 
zeroed during signal argument copying • 
6-6 

Fault handlers • 6-19 

effect of noncontinuable execution on • 
6-14 

method for setting up in VAX Ada* 
6-19 

FDL (File Definition Language) • 2-9 

most likely attributes for Ada files *2-16 
primary attributes of *2-10 
rules for using *2-14 
secondary attributes of *2-10 
using attributes to tune external files • 
2-28 

using to give values to FORM 
parameters • 2-9 
File objects • 2-2 

creating or opening • 2-2 
FILE parameter • 2-5 


File terminator 

in Ada text fil • 2-66 
FILE_PROTECTION_FLAGS_TYPE • A-3 
FILE_PROTECTION_REC_TYPE • A-3 
FILE_PROTECTION_TYPE • A-3 
Files 

Ada direct • 2-9 
Ada indexed • 2-9 
Ada relative • 2-9 
buffering text *2-66 
carriage control of text *2-67 
carriage control options for Ada text • 
2-68 

changing creation-time attributes of 
external • 2-29 

consistency checking of attributes of 
external • 2-30 

creation-time attributes of external* 

2-29 

default attributes for Ada direct *2-40 
default attributes for Ada indexed • 2-48 
default attributes for Ada text *2-61 
default attributes for external • 2-30 
default attributes for relative • 2-44 
default attributes of Ada sequential • 
2-37 

default characteristics of *2-2 
default logical names for VAX/VMS* 

2-7 

default specifications for *2-6 
defining keys in indexed • 2-4 
definition of Ada • 2-2 
definition of external *2-2 
direct • 2-3 
external • 2-2 

FDL attributes for tuning external • 2-28 
FORTRAN carriage control characters for 
Ada text • 2-70 

implementation of Ada text *2-61 
indexed • 2-4 
locking records in • 2-32 
logical names for *2-6 
mixed-type • 2-33 

most likely FDL attributes for external • 
2-16 

naming external • 2-5 
optimizing external • 2-16 
optimizing performance of *2-32 
possible carriage-control attributes for 
Ada text • 2-67 
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Files (cont'd.) 

process permanent • 2-8, 2-73 
reading indexed • 2-49 
relative • 2-3 

rules for specifying FDL attributes for 
external *2-14 

run-time attributes of external • 2-29 
sequential • 2-2 
sharing • 2-30 

specifying key information for indexed • 
2-47 

specifying record size for Ada direct* 
2-40 

specifying record size for Ada relative* 
2-43 

specifying RMS attributes of *2-9 
terminators in Ada text *2-64 
text* 2-4 

using FORM parameter to control 
attributes of external • 2-9 
using FORM paramter to control sharing 
of *2-31 

writing VAX/VMS specifications for* 
2-5 

Fixed-point types 
packing *3-19 
passing parameters of *4-8 
representation of *3-12 
returning as function results *4-12 
FLOAT 

representation of *3-3 
storage size of *3-3 
FLOAT_MATH_LIB package • A-45 
FLOAT_MATH_LIB predefined instantation 
example of using *5-26 
FL0AT_TEXT_I0 package • 2-71, A-45 
Floating-point objects 

default alignment of *3-26 
Floating-point types 

D_floating representation • 3-9 
F_floating representation • 3-7 
G_floating representation • 3-9 
H_floating representation • 3-1 1 
packing *3-19 
passing parameters of *4-8 
representation of *3-3 
returning as function results *4-12 
FLOOVEMAT* A-43 
FLOUNDMAT* A-43 
FORM 

see also Exceptions, Ada format 
see also Exceptions, VMS format 


FORM (cont'd.) 

optional parameter to EXP0RT_ 
EXCEPTION pragma *6-12 
optional parameter to IMPORT— 
EXCEPTION pragma *6-10 
FORM parameter • 2-9, 2-30, 2-31 
see also CREATE procedure, OPEN 
procedure 

association with FDL string or file *2-9 
rules for specifying • 2-10 
specifying record locking with *2-32 
using to name an external file *2-5 
using to specify carriage control 
attributes • 2-67 
FORTRAN 

exporting an Ada function to *4-17 
handling exceptions propagated from* 
6-15 

importing a routine from • 4-20 
nonreentrancy of run-time library *7-27 
sharing common blocks with *3-34 
Frame pointer (FP) • 4-5 
Frames 

definition of Ada vs. VAX/VMS *6-3 
distinction between Ada and stack *6-2 
exception handlers for *6-2 
Full reentrancy • 7-27 
FUNCTION_CODE_TYPE • A-3 
Functions 

values returned from *4-11 

G 


G_FL0AT 

representation of *3-3 
storage size of *3-3 
G_floating representation • 3-9 
Generic instantiations 

creating library packages of *8-4 
Generic subprograms 

using pragma INLINE with instantiations 
of *8-7 

GET_ITEM *2-33 
GET-LINE *2-63 

H 


H_FLOAT 

representation of *3-3 
storage size of *3-3 
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H_floating representation • 3-1 1 

i 


Import pragmas • 4-14, 4-17 

using to write VAX/VMS interface 
routines • 5-1 

IMPORT_EXCEPTION pragma *6-10 
and N0N_ADA_ERR0R *6-19 
examples of use *6-12 
use of to give user-defined exceptions 
VMS format • 6-6 

using to associate an Ada exception 
with a VAX condition* 6-10 
IMPORT_FUNCTION pragma *4-17 
IMP0RT_0BJECT pragma • 3-30 
IMPORT—PROCEDURE pragma *4-14, 4-17 
IMPORT_VALUED_PROCEDURE pragma* 
4-17 

using to call SYS$TRNLNM system 
service *5-19 

using to write system routine interfaces 
•5-18 

Importing exceptions • 6-10 
INDEXED_IO package*2-2, 2-4, 2-32, A-2 
default file attributes provided by *2-48 
example of using *2-50 
INDEXED_MIXED_IO package *2-2, 2-4, 
2-33, A-2 

default file attributes provided by • 2-49 
example of using *2-57 
INHIB_MSG • A-14 
INLINE pragma • 8-5 
Input 

nonterminal • 2-66 
terminal • 2-66 
Input-output 

avoiding during task call to 
SYSSSET AST • 7-33 
avoiding to avoid AST deadlock • 7-39 
interaction of with tasking *2-73 
Input-output packages *2-2 
INTEGER 

representation of *3-1 
INTEGER objects 

default alignment of *3-26 
Integer types 

declaring unsigned • 3-21 

packing *3-19 

passing parameters of *4-8 


Integer types (cont'd.) 

returning as function results *4-12 
INTEGER_TEXT_IO package • 2-71, A-45 
Integers 

range of values for predefined • 3-2 
representation of *3-1 
storage size of • 3-1 
INVARGMAT* A-43 
I0_EXCEPTIONS package *2-74, A-2 
exceptions predefined in • 6-5 
IOSB_TYPE • A-3 
ITEM—LIST—2—TYPE • A-3 
ITEM_LIST_TYPE • A-3 

L 


LIB$MATCH_COND routine 

interface for in package CONDITION— 
HANDLING *5-23 

provided in CONDITION_HANDLING 
package • 5-1 
LIBSSIGNAL routine 

provided in CONDITION-HANDLING 
package • 5-1 
LIB$STOP routine 

provided in CONDITION-HANDLING 
package • 5-1 

use of to implement the raising of an 
exception • 6-4 

use of to implement the raising of 
exceptions • 6-3 
used in exception handling *6-1 
Library packages 

tasks declared in • 6-2 
Line terminator 

in Ada text file • 2-64 
Linker 

program section allocation by • 3-30 
use of to perform link-time object size 
checking • 3-32, 3-35 
LOCK-ERROR 

raised on access to a locked record • 
2-32 

LOCK_ID_TYPE • A-3 
LOCK_STATUS_BLOCK_TYPE • A-3 
LOCK_VALUE_BLOCK_TYPE • A-3 
LOG • A-43 
LOG 10* A-43 
LOG2 • A-43 
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Logical names 

in coding exception condition values* 
6-1 

using to denote file specifications • 2-6 
VAX/VMS tables for *2-7 

LOGICAl_NAME-TYPE • A-3 

LOGZERNEG • A-43 
LONG_FLOAT 

representation of *3-3 
storage size of *3-3 
LONG_FLOAT pragma • 3-7 

effect on type LONG_FLOAT • 3-3 
effect on user-defined floating-point 
types • 3-5 

LONG_FLOAT_MATH_LIB package • A-45 
LONG—FLOAT—TEXT—10 package • 2-71, 
A-45 

LONG_LONG_FLOAT 
representation of *3-3 
storage size of *3-3 

LONG—LONG—FLOAT—MATH—LIB package • 
A-45 

LONG—LONG—FLOAT—TEXT—10 package* 
2-71, A-45 

M 


MACHINE_SIZE attribute • 3-27 
MACRO 

exporting and importing objects from* 
3-30 

sharing variables with *3-34 
Main program 

as environment task *7-2 
propagation of exceptions to *6-2 
MASK_PRIVILEGES_TYPE • A-3 
MATCH-COND* A-14 
Math routines 

example of importing from VAX Run¬ 
Time Library *6-11 

MATH—LIB package *5-1, 5-26, A-42 
instantiation of *8-4 
Mechanism arguments 

in raising exceptions • 6-1 
using VAX Ada packages to examine* 
6-19 

Mixed-language programming • 4-1 
exception handling in *6-10 
with tasks • 7-27 
MODE parameter • 2-31 


Model numbers *3-3 

defined for each floating-point type *3-4 
determining for user-defined types *3-5 
MSG-NO* A-14 


IV 


NAM (name block) 

record type declared for in package 
STARLET *5-12 
NAME parameter • 2-5 
NEW-LINE *2-65, 2-66 
NEW—PAGE • 2-65, 2-66 
N0N_ADA_ERR0R 

as match for imported VAX conditions* 
6-7 

encoding of • 6-18 

use of to match VAX conditions* 6-18 
NULL-PARAMETER attribute • 4-19, 5-8 
example of use in package STARLET • 
5-9 

NUMERIC-ERROR 

as match for VAX conditions • 6-7 


0 


Objects 

allocation of • 8-1 

sharing storage of with non-Ada code* 
3-30 

storage of • 3-1 

OPEN procedure *2-2, 2-29, 2-30 
FILE parameter • 2-5 
FORM parameter • 2-9, 2-31 
MODE parameter* 2-31 
NAME parameter • 2-5 
Optimizations • 8-8 
suppressing • 8-3 
Output 

nonterminal • 2-66 
terminal • 2-66 


P 


PACK pragma *3-18 

using to change default array 
representations *3-13 
Page terminator 

in Ada text file *2-64 
PAGE_PROTECTION_TYPE • A-3 
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Parameter passing 

between languages and system service 
routines • 5-7 
Parameters 

Ada semantics for passing - 4-7 
default descriptor classes for passing 
array type • 4-9 

default in VAX Ada *4-15, 5-8 
optional in RMS routines declared in 
package STARLET *5-11 
optional in system and Run-Time Library 
routines • 5-8 

overloading optional in package 
STARLET - 5-9 

overriding default passing mechanisms 
for* 4-18 

passing access type *4-10 
passing Ada subprograms as to system 
routines *5-18 
passing address type *4-11 
passing array type *4-9 
passing by descriptor to an exported 
Ada subprogram • 4-15 
passing by descriptor to Run-Time 
Library routines • 4-21 
passing mechanisms for *4-6 
passing record type - 4-10 
passing scalar type *4-8 
passing scalar, access, and address 
type • 4-7 

passing task type *4-11 
passing to imported routines with 

DESCRIPTOR mechanism option • 
4-20 

passing to imported routines with 
REFERENCE mechanism option • 
4-19 

passing to imported routines with 

VALUE mechanism option* 4-19 
PASCAL 

exporting an Ada subprogram to - 4-15 
exporting and importing objects from • 
3-30 

sharing variables with • 3-34 
PL/I 

exporting and importing objects from • 
3-30 

sharing variables with • 3-34 
PRIORITY pragma 

for setting task priorities • 7-16 


PRIORITY pragma (cont'd.) 

using to overcome busy waiting *7-22 
PROCESS_ID__TYPE • A-3 
PROCESS_NAME_TYPE • A-3 
Processor status word (PSW) - 4-5 
Program counter (PC) *4-5 
Program sections • 3-29 

definition of attributes • 3-29 
establishing with PSECT_OBJECT 
pragma • 3-34 

PSECT—OBJECT pragma • 3-30, 3-34 
attributes of objects specified with • 
3-34 

Psects 

see Program sections 
PUT_ITEM • 2-33 
PUT—LINE • 2-66 


R 


RAB (record access block) 

record type declared for in package 
STARLET - 5-12 
RAB_TYPE - A-3 
Record 

simple *4-14 
Record discriminants 

representation of in record layout *3-13 
Record objects 

controlling allocation of with alignments 
•3-25 

default alignment of *3-26 
Record types 

aligning components of *3-24 
dynamic components in - 3-14 
packing *3-19 

passing parameters of *4-10 
passing simple as parameters with 
VALUE mechanism option* 4-19 
representation clauses with - 3-13, 3-22 
representation of *3-13 
returning as function results *4-14 
size of* 3-15 

using representation clauses to force 
efficient storage of - 3-23 
Record variants 

effect of pragma PACK on • 3-20 
representation clauses with • 3-22 
representation of in record layouts • 
3-14 
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Recursive reentrancy • 7-26 
Reentrancy 

avoiding non *7-27 
definition of kinds of *7-26 
in mixed-language tasking programs 0 
7-27 

Reference mechanism • 4-7 

passing access type parameters by* 
4-10 

passing address type parameters by* 
4-11 

passing array type parameters by *4-9 
passing record type parameters by* 
4-10 

passing task type parameters by *4-1 1 
REFERENCE mechanism option *4-19 
in import pragmas *4-18 
Reference semantics • 4-7 

passing array type parameters by *4-9 
passing record type parameters by • 

4- 10 

passing task type parameters by *4-1 1 
Registers 

use of to allocate object storage *8-1 
RELATIVE_IO package *2-2, 2-4, A-2 
default attributes provided by *2-44 
example of using • 2-47 
RELATIVE_MIXED_IO package *2-2, 2-4, 
2-33, A-2 

default file attributes provided by • 2-45 
Rendezvous • 7-2 

during AST handling • 7-37 
Represenation clauses 

specifying alignment with *3-24 
Representation clauses *3-18 
enumeration • 3-21 
length • 3-21 
record • 3-22 

RIGHTS_HOLDER_TYPE • A-3 
RIGHTS_ID_TYPE • A-3 
RMS (Record Management Services) 
calling from an Ada program • 5-26 
calling with package STARLET *5-5 
example of using control blocks *5-15 
STARLET type declarations for *5-12 
testing condition values returned by* 

5- 23 
RMS services 

calling asynchronous from tasks *7-31 


RMS_ASYNCH_OPERATIONS package* 
A-20 

ROPRAND* A-43 


S 


Safe numbers • 3-4 

defined for each floating-point type *3-5 
Scalar types 

passing parameters of *4-7 
passing simple as parameters with 
DESCRIPTOR mechanism option* 
4-20 

returning as function results *4-12 
SECTION—ACCESS_ID_TYPE • A-3 
SECTION_ID_TYPE • A-3 
SECTION_NAME_TYPE • A-3 

SEQUENTIAI_10 package *2-2, 2-3, 2-32, 

A-2 

default file attributes provided by *2-37 
example of using *2-40 
SEQUENTIAL_MIXED_IO 

default file attributes provided by *2-38 

SEQUENTIAI_MIXED_I0 package *2-2, 

2-3, 2-33, A-2 
Serial reentrancy • 7-26 
SEVERITY* A-14 
Shared variables 

in tasking program *7-24 
SHORT-INTEGER 

representation of *3-1 
SHORT_INTEGER objects 
default alignment of *3-26 
SHORT—INTEGER—TEXT—10 package* 
2-71, A-45 

SHORT_SHORT_INTEGER 
representation of *3-1 
SHORT_SHORT_INTEGER objects 
default alignment of *3-26 
SHORT—SHORT—INTEGER—TEXT—10 
package • 2-71, A-45 
SIGNAL* A-14 
Signal arguments 

in raising exceptions • 6-1 
Simple record *4-14 
SIN* A-43 
SIND* A-43 
SINH* A-43 
SIZE attribute • 3-26 
SKIP-LINE • 2-63 
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SORT* A-43 
SQUROONEG • A-43 
Stack 

use of to allocate storage *8-2 
STANDARD package • A-2 

exceptions predefined in • 6-5 
recompilation of with pragma LONG_ 
FLOAT *3-7 

STARLET package* 5-1, 7-29, A-3 

example of using RMS control blocks 
from *5-15 

example of using to call SYSSTRNLNM 
system service *5-5 
naming conventions used in *5-7 
provision of initialization constants for 
record types *5-13 
severity codes provided in *5-23 
specification of optional parameters in* 
5-7 

specification of types defined in • A-3 
type declarations in for RMS control 
blocks *5-12 

use of IMPORT_VALUED_PROCEDURE 
pragma in • 5-18 

using to call VAX/VMS system services 
•5-5 

using to call RMS services *5-5 
Static memory 

use of to allocate storage *8-2 
Status values> constants defined in 
package STARLET • 5-24 
STOP* A-14 
STOP command 

entering after CTRL/Y in tasking 
program • 7-23 
Storage allocation • 8-1 
optimization of *8-2 
STORAGE-ERROR 

raised for stack overflow • 7-13, 7-14 
STORAGE-SIZE attribute 

to control task working storage area • 
7-13 

String • 4-9 
String types 

passing as parameters with 

DESCRIPTOR mechanism option* 
4-20 
Subprograms 

calling from non-Ada AST service 
routines • 7-38 


Subprograms (cont'd.) 
implicit inlining of *8-8 
importing and exporting • 4-14 
inlining • 8-5 

passing as parameters to system 
routines *5-18 
SUCCESS* A-14 
SUPPRESS-ALL pragma 

use of to suppress run-time checks • 6-8 
SYSSCOMMAND logical name *2-7, 2-73 
equivalence strings for *2-9 
representing process permanent file* 

2-8 

SYS$CRMPSC system service 
example of using *5-15 
SYSSDCLEXH system service 
calling from tasks *7-35 
SYS$DISK logical name *2-7 
SYS$ERR0R logical name *2-7, 2-73 
equivalence strings for *2-9 
output file for error messages • 6-2 
representing process permanent file* 

2-8 

SYS$EXIT system service 

avoiding calls to from tasks *7-34 
SYSSHIBER system service 

avoiding calls to from tasks *7-33 
SYSSINPUT logical name *2-7, 2-73 
equivalence strings for *2-9 
representing process permanent file* 

2-8 

SYS$LOGIN logical name *2-7 
SYS$NET logical name *2-7 
SYSSOPEN RMS routine 
example of calling *5-15 
SYSSOUTPUT logical name *2-7, 2-73 
equivalence strings for *2-9 
output file for error messages • 6-2 
representing process permanent file* 

2-8 

SYS$SCRATCH logical name *2-7 
SYSSSETAST system service *7-32 
SYSSTRNLNM system service 

calling using package STARLET *5-5 
example of calling using IMPORT— 
VALUED-PROCEDURE pragma* 
5-19 

SYSTEM package *5-1, A-2 
ADDRESS_ZERO in *4-19 
exceptions predefined in *6-5 
N0N_ADA_ERR0R in *6-7, 6-18 
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SYSTEM package (cont'd.) 

type ADDRESS in *3-18, 8-3 

T 


TAN • A-43 
TAND • A-43 
TANH • A-43 

Task control block *7-2, 7-9 

address of as value of task object *3-18 
estimating size of* 7-10 
Task deadlock • 7-17 

caused by SYS$SETAST • 7-32 
circular-calling *7-18 
due to busy waiting *7-21 
during AST handling • 7-37 
during call from non-Ada AST service 
routine • 7-38 
dynamic-calling *7-18 
exception-induced *7-19 
self-calling *7-18 
Task objects 

default alignment of *3-26 
Task stack* 7-2, 7-12 

detecting overflow of *7-13 
estimating working storage area *7-13 
for main task *7-12 

increasing and decreasing the top guard 
area of • 7-13 

increasing and decreasing the working 
area of • 7-13 

overflow when calling non-Ada code* 
7-14 

top guard area of* 7-12 
using top guard area for detecting 
overflow *7-14 

working storage area of *7-12 
Task switching • 7-2, 7-15 
Task synchronization • 7-2 
Task types 

packing *3-19 

passing parameters of *4-11 
representation of *3-18 
returning as function results *4-12 
TASK_BRKTHRUW • A-21 
TASK_ENQW • A-21 
TASK—GETDVIW • A-2 1 
TASK_GETJPIW • A-21 
TASK—GETLKIW • A-2 1 
TASK_GETSYIW • A-2 1 
TASK_QIOW • A-2 1 


TASK_RMS_CLOSE • A-21 
TASK_RMS_CONNECT • A-21 
TASK_RMS_CRE ATE • A-21 
TASK_RMS_DELETE • A-21 
TASK_RMS_DISCONNECT • A-21 
TASK_RMS_DISPLAY • A-21 
TASK_RMS_ENTER • A-21 
TASK_RMS_ERASE • A-21 
TASK_RMS_EXTEND • A-21 
TASK_RMS_FIND • A-21 
TASK_RMS_FLUSH • A-21 
TASK_RMS_FREE • A-21 
TASK_RMS_GET • A-21 
T ASK_RMS_NXTVOL • A-21 
TASK_RMS_OPEN • A-21 
TASK_RMS_PARSE • A-21 
T ASK_RMS_PUT • A-21 
TASK_RMS_RE AD • A-21 
TASK_RMS_RELEASE • A-21 
TASK_RMS_REMOVE • A-21 
TASK_RMS_RENAME • A-21 
TASK._RMS_REWIND • A-21 
TASK_RMS_SEARCH • A-21 
TASK_RMS_SPACE • A-21 
TASK_RMS_TRUNCATE • A-21 
TASK_RMS_UPDATE • A-21 
TASK_RMS_WAIT • A-21 
TASK_RMS_WRITE • A-21 
TASK_SNDJBCW • A-21 
TASK_STORAGE pragma 

to control task stack top guard area • 
7-14 

TASK_UPDSECW • A-21 
Tasking 

interaction of with input-output • 2-74 
TASKING_SERVICES package • 7-31, 7-32, 
7-35, A-20 

use of overloading for optional 
parameters in • 5-26 
Tasks• 7-20 

busy waiting of* 7-19, 7-26 
calling non-Ada routines from *7-27 
calling system services from *7-29 
changing priority to improve 
performance • 7-43 
deadlock with *7-17 
definition of • 7-2 

delivery of ASTs to completed or 
abnormal • 7-38 

dependence on masters *7-2, 7-9 
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Tasks (cont'd.) 

effect of priority on action taken after 
CTRL/Y • 7-23 
environment • 7-2 
example of using 0 7-3 
first-in-first-out scheduling of *7-16 
handling ASTs from *7-37 
in context of single process *7-2 
increasing concurrency of when calling 
system services • 7-31 
increasing concurrency with TASKING— 
SERVICES *7-32 

interaction with exception handling* 

6- 19 

interference of busy waiting with 
scheduling • 7-21 
interrupting with CTRL/Y • 7-23 
main • 7-2, 7-10 

measuring and tuning performance* 

7- 43 

propagation of exceptions to*6-2, 6-13 
raising exceptions at point of 
rendezvous • 6-4 
reentrancy with *7-26 
round-robin scheduling of *7-16 
serializing to prevent reentry *7-29 
sharing variables with *7-24 
storage allocated for *7-9 
storage allocated for when AST 
delivered • 7-38 

synchronization of variable access in • 
7-25, 7-26 

system services to avoid calling from • 
7-32 

using abort statements in *7-22 
using delay statement to force 
completion of abnormal • 7-22 
TERMINATED attribute 

value of during task AST handling • 7-38 
TEXT—IO package *2-2, 2-5, 2-33, A-2 
default file attributes provided by *2-61 
example of using *2-62 
instantiation of operations in • 8-4 
predefined instantiations for *2-71 
TIME_NAME_TYPE • A-3 
TIME-SLICE pragma *7-43 

using to cause round-robin task 
scheduling *7-16 

using to overcome busy waiting *7-22 
TT logical name • 2 - 1 , 2-73 


Types 

representation of *3-1 
VAX Ada equivalents for VAX data* 

5-3 

U 


UIC_TYPE« A-3 
SUNWIND routine 

use of to invoke an exception handler* 

6-3 

USE-ERROR 

raised for concurrent opening of 
magnetic tape files *2-31 
raised for FDL errors in FORM parameter 
•2-14 

raised for mismatch of file attributes* 
2-29, 2-30 

raised for opening an open file *2-32 
raised when writing text files *2-61 
USER_ARG_TYPE • A-3 

_ 


Value mechanism • 4-7 
VALUE mechanism option *4-19 
in import pragmas *4-18 
Variables 

asynchronous modification of in tasking 
program • 7-24 

indivisible access of in tasking program • 

7-26 

VAX Procedure Calling Standard 
conformance of Run-Time Library 
routines to • 5-7 

conformance of system services to *5-7 
conformance of VAX Ada to *4-1 
interface for function return values • 

4- 1 1 

parameter-passing mechanisms specified 
by • 4-6 

VAX Run-Time Library routines 

calling from an Ada program • 5-26 
calling from tasks *7-12 
declaring record types for *3-22 
testing condition values returned by* 

5- 23 

VAX/VMS Linker 
see Linker 
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VAX/VMS system routines 

declaring record types for *3-22 
VAX/VMS system services 
calling asynchronous • 5-25 
calling asynchronous from tasks *7-31 
calling from an Ada program • 5-26 
calling from tasks • 7-12 
calling with package STARLET • 5-5 
example of calling using package 
STARLET • 5-5 

example of item-list structure in call to* 
5-5 

testing condition values returned by* 
5-23 

VAX/VMS utility routines 

calling from an Ada program *5-26 
VOLATILE pragma *7-24 

example of use in system service call* 
5-5 

example of using with RMS control 
blocks *5-15 

with address determined by ADDRESS 
attribute • 8-3 

W 


WORD_COND_VALUE_TYPE • A-14 

X 


XAB (extended attribute block) 

record type declared for in package 
STARLET *5-12 


Z 


$ZERO program section *3-29 
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